Field Watcher

From ServiceNow Wiki
Home > Script > Debugging > Field Watcher
Jump to: navigation, search
Note
Note: This article applies to Fuji. For more current information, see Field Watcher at http://docs.servicenow.com

The ServiceNow Wiki is no longer being updated. Please refer to http://docs.servicenow.com for the latest product documentation.


Scripting Glide and Jelly
Related Topics
Knowledge.gif Get the Glide Reference Book

1 Overview

The Field Watcher tool tracks and displays all actions that the system performs on a selected form field. Administrators can use the field watcher to figure out what happens to the field and how the value of the field changes when an event such as the firing of a business rule or enforcement of a data policy, takes place. Administrators can also impersonate non-admin users to debug what happens when those users make changes on an instance. Only one field can be watched at a time.

Field Watcher is available on all instances starting with the Dublin release.

2 How the Field Watcher Works

The Field Watcher tool logs activity when any of the following events occur on a field:

  • The default value is set on the field.
  • User access rights for the field change due to an ACL or dictionary setting.
  • A data policy prevents the value from being set.
  • A reference qualifier query of the field value executes.
  • A UI policy changes a field to or from read-only, visible, mandatory, or editable.
  • A dependent value in another field restricts field choices.
  • The value of the field is set or changed based on:
    • Assignment rules
    • Actions from an engine, such as the workflow engine
    • Business rules
    • User entries
    • Client scripts
    • UI actions
Note
Note: The field watcher works only on form fields. It cannot be used on list fields. Also, field watcher is not available on password-protected fields or encrypted fields.


3 Using Field Watcher

  1. Navigate to the form for which you want to view field-level debugging information.
  2. Activate Field Watcher by right-clicking any field label on a form and select Watch - '<field name>'.
    The debug icon Debug.gifx.gif appears next to the field label. From this point on, the Field Watcher records every action taken on the selected field. For example, if you are watching a Priority field, if the priority is changed from Moderate to Low and the the record is updated, the Field Watcher will display information about that change.
  3. View the Field Watcher log by clicking the debug icon.
    A new pane opens at the bottom of the screen, showing a Field Watcher tab. It may also show tabs for JavaScript Logging and JavaScript Debugger.
    Field Watcher Full Screen.png
  4. Click the Field Watcher tab, if needed.
  5. Stop watching a field by right-clicking the field and selecting Unwatch - <field name>. To watch another field, right-click that field and select Watch - <field name>.
  6. Clear the Field Watcher log by clicking the clear log button Field Watcher Clear Log Button.png.
  7. Resize the Field Watcher pane by dragging the splitter bar up or down. Dragging the splitter bar to the bottom of the screen closes the Field Watcher pane. Reopen the pane by clicking the debug icon Debug.gifx.gif again.


3.1 Setting Up the Field Watcher Tab

The left side of the Field Watcher tab shows the following information for the watched field:

  • Table: table to which the field belongs.
  • Element: field label.
  • Type: type of data stored in the field.
  • Dependent: field on which the current field depends.
  • Reference: table from which the field's value originates, if applicable.
  • Reference Qual: reference qualifiers that may be restricting data on the field.
  • Attributes: attributes on the field as specified in the dictionary entry for that field.

On the right side of the Field Watcher tab, select the types of activity information you want to see for the selected field. Clear the check box for any type of information that is not needed.

3.2 Viewing Information for the Watched Field

When information for a watched field is changed and the record is updated, the Field Watcher tab displays relevant information at the bottom.

Field Watcher Viewing Data.png

Field watcher information includes:

  • Timestamp: time the field was changed using the HH:MM:SS (ms) format.
    • Orange text: server-side changes, such as ACLs.
    • Blue text: client-side changes, such as client scripts.
  • Type of object that changed the field and its associated name: The type of item that changed on the field; for example, CLIENT SCRIPT, BUSINESS RULE, or ACL. In the case of scripts, business rules, or other configuration-type fields, field watcher displays the name of the script or business rule that changed the field, if any. Click the name to go directly to the record for that item.
  • Old and new values: The old and new values for the field, if the value changed0. Field watcher does not record the value if it was inserted in the form by default at the time the record was created.
  • Additional information: Call tracing information, such as the name of the script engine or workflow that changed the field. Click the plus icon to expand the selection.
    • Orange text: Indicates server-side activity.
    • Blue text: Indicates client-side activity.

3.3 Watching a Hidden Field

Administrators may have need to watch a field that is hidden on a field. To watch a hidden field:

  1. Use the dictionary to determine the column name of the field.
  2. Elevate privileges to the security_admin role.
  3. Navigate to System Definition > Scripts Background.
  4. In Run script (JavaScript executed on server), enter the following command:
    gs.getSession().setWatchField("hidden_field");
    
    Replace hidden_field with the column name of the hidden field.
  5. Navigate to the form containing the missing field.
    The Field Watcher tab output contains information about the hidden field.

4 Example: Watching the Incident Priority

The following example shows what happens to the Priority field on the Incident form when both the Impact and Urgency fields change. The Incident form has two client-side data lookups change the priority. Additionally, server-side ACLs and the data lookup engine fire when the record is saved. Finally, a client-side UI policy sets the Priority field back to read-only, which is the default setting.

Original Values
  • Priority: 1 - Critical
  • Impact: 1 - High
  • Urgency: 1 - High
First Change
  1. The user changes the Impact value to 3 - Low.
  2. The priority automatically changes to 3 - Moderate based on the Priority Lookup data lookup definition used by default in ServiceNow incidents.
    Note: At this point, the record has not been saved.
Second Change
  1. The user changes the Urgency value to 2 - Medium.
  2. The priority automatically changes to 4 - Low based on the same Priority Lookup data lookup definition.
  3. The user saves the record by right-clicking the form header and choosing Save.
Field watcher example: Incident priority change

Note
Note: The values that change from 1 to 3, and then from 3 to 4, refer to the numerical values in the choice list.


5 Tutorials

The following video demonstrates how to perform field-level debugging with the field watcher.

Debugging with Field Watcher

Note
Note: To view more video tutorials, see ServiceNow Video Tutorials.
Was this article helpful?
Yes, I found what I needed
No, I need more assistance