debug assignment rules servicenow

• ServiceNow Consulting Services
• ServiceNow IT Workflows
• ServiceNow Customer Workflows
• ServiceNow Employee Workflows
• Hyperautomation
• ServiceNow Implementation Services
• ServiceNow Integration Services
• ServiceNow Managed Services
• ServiceNow for Manufacturing Industry
• Digital Transformation In Banking
• Digital Transformation In Insurance
• Digital Transformation in Wealth & Asset Management
• Digital Transformation in Life Sciences
• Digital Transformation in Hospitals
• Digital Transformation for Payers
• Data Migration Utility
• 360 Degree Business Assessment
• ServiceNow Dx Support
• Service Automate
• Rome Release
• Case Studies
• News Events
• Infographic
• Thought Leadership

Handling Assignment Rules in ServiceNow

In ServiceNow, if one is looking for automatic assignments then he can rely on the instance’s ability to assign the tasks automatically to different users and groups depending on the specified conditions. In order to achieve this, ServiceNow has the following modules:

• Assignment Lookup Rules
• Assignment Rules

Assignment Lookup Rules:

This module appears under the ‘System Policy application’ menu. This table is basically generated out of the box as its definition is provided in the ‘Data Lookup Definition’ table in the instance, specifically for field assignments in the incident table. Assignment lookup rules mainly provide the functionality of changing any field value and not just the assignment fields.

Assignment Rules:

This module appears under the ‘System Policy application’ menu. It helps to automatically assign the tasks to a particular user or a particular group using the assigned_to and assignment_group fields respectively, depending on the specified set of conditions. One can define these assignment rules readily for their desired table.

Following are the steps for defining the assignment rule:

• Navigate to System Policy -> Assignment -> New

• From the above figure, one can see that the dot-walking can also be done in the condition builder field. Just select the ‘Show Related Fields’ option in the condition and then select the appropriate attribute.
• Further, in the ‘Assign To’ tab, select the appropriate user and group to whom the task is to be assigned.

If two assignment rules conflict, then the assignment rule with the lowest execution order runs first. The lower the execution order, the higher is the precedence.

Distinguishing Factors between the Data Lookup Rules and Assignment Rules:

Precedence among the assignment rule and business rule:.

In certain circumstances, the business rules gain precedence over the assignment rules.

The business rules and assignments rules run in the following order:

• All the ‘before record insert’ business rules having order less than 1000.
• First and foremost, assignment rule with lowest execution order and matching condition.
• All the ‘before record insert’ business rules having order more than 1000.
• All the ‘after record insert’ business rules.

We are pretty sure that this blog must have given an overview of dealing with Assignment Rules in ServiceNow.

Any comments\suggestions are most welcome. We have posted further blogs as well on other topics and will frequently come back with something innovative.

Share This Story, Choose Your Platform!

  Blog Home

  announcements,   solutions, recent posts, now experience, developer site reimagined, orlando: integrationhub, welcome brad tilton, developer site changes, share this post, debugging and you.

#Debugging , #REST API Explorer , #REST Debugging

4 minute read

Debugging in ServiceNow is am essential skill to master. An array of tools are available to help developers understand what the system is doing and narrow down where unexpected behavior is happening. Today we will look specifically at several ways to debug when doing scripting.

Session Debug

A feature released in the New York release unified the session debugging modules. A session is a unique login for a unique user - typically one browser on one device. Now when selecting a session debugging option from the navigation, a new window launches.

The session log and debugging options are available in this interface. On the left, you have the transaction list available. Selecting one of the transactions will jump you to the start of that transaction in the log entries. The search filter does what you would expect, filter the log entries to just lines that contain the search term. The filters in the dropdowns can be handy when many things are happening at once.

It can be confusing to see a filter for debugging options like business rules and also a setting for business rules . The filter narrows the displayed log, where the settings toggle debugging options on/off. Only log entries for the debugging types that are enabled will be visible and then filterable. Most debugging will not need all debugging types turned on, as that will produce to much noise that must be filtered to find the information you as the developer are looking to find.

When should you use the session debugging? session debugging has a variety of options from ACL to Business Rules to Upgrade . What kind of information you are seeking will lead you to one or several of the debugging options. If you wish to know why your new script isn’t adjusting a field as you expect, then the business rule would be my first visit unless you can utilize a breakpoint. (we will talk more about breakpoints later). Access can be easily checked by using the security debugging along with impersonation.

The joining of all the logs into one powerful interface should help you find the root cause of whatever you are inspecting. Utilize the clear log tool between tries to help lessen the noise when applicable. Knowing how to best filter, find, and examine the results will enable you to develop faster and hopefully with fewer errors. One way to do that is to try out the debugging before you encounter an issue. Give it a try on an update of a record you are familiar with before adjusting any business logic. That way, you have some idea of what things look like before you changed anything.

Breakpoints

Breakpoints and Conditional Breakpoints are where we insert a pause in the execution flow. That pausing leads to an essential note: breakpoints only apply in direct synchronous sessions. Only the developer that set the breakpoint, and only in their session in which a script debugger window is opened, will be paused. Thus you can safely debug without impacting your fellow developers. You can read more about the details of the script debugger in the detailed blog entry.

Leveraging the script breakpoints can be a powerful tool to reduce the need for log entries to validate field and object values. Using the inspector, you can see the value for all of the variables as you step through your script and other scripts called later in the execution flow. Figuring out how and why your result didn’t reach the outcome you inspected can be quickly determined with this method.

A Tip is invoking an asynchronous process directly through background scripts or the rest API explorer.

No entry on debugging would be complete without at least a reference to the old stand-by, logging . Inserting logs can be quite useful especially for warn and error statements once a given script is in use in production. I discourage system log entries for normal operations as they pollute your codebase and log table with noise. One note: if operating in the global scope, use the source parameter to help facilitate filtering.

The node logs are the point of last resort for most debugging. ServiceNow logs quite a bit of detail inside of the node logs. I might do a future entry just on node logs as there is lots to cover but isn’t a general use case. If you leverage the other options available, you can typically avoid having to dive into the detailed node logs.

Happy Debugging

Hopefully, these tips will help you use the tools available to you as a ServiceNow developer. Please share in the comments any other great debugging ideas that I did not document here. Time to get back to building my application!

• Adding ATF to Existing Projects
• 2020 ServiceNow Developer MVPs

Developer Blog

Written with by the Developer Program team

Application Development 49

Developer Program 17

Off Topic 1

Solutions 33

Tutorials 8

User Experience 1

© 2020 ServiceNow Developer Blog . Powered by Hugo

Classic business rules

A business rule is a server-side script that runs when a\n record is displayed, inserted, updated, or deleted, or when a table is queried.

• How business rules work

To configure business rules, you first need to determine when the business rule should run and what action it should take.

When business rules run

• When to run the business rule in relation to a database operation.
• What record operation the business rule applies to.
• Asynchronous business rules do not have access to the previous version of a record. Therefore, the changes() , changesTo() , and changesFrom() \n GlideElement methods do not work with async rule script. However, the condition builder and condition field (advanced view) both support the changes() ,\n changesTo() , and changesFrom() methods.
• Business rules do not honor ACLs until you want them to be honored. For more information, see Relationship between Business Rules and Access Control Rules (ACLs)

Business rule actions

• Changing field values on a form that the user is updating. Field values can be set to specific values available for that field, values copied from other fields, and relative values determined by the user's role.
• Displaying information messages to the user.
• Changing values of child tasks based on changes to parent tasks.
• Preventing users from accessing or modifying certain fields on a form.
• Aborting the current database transaction. For example, if certain conditions are met, prevent the user from saving the record in the database.

Prevent recursive business rules

Avoid using current.update() in a business rule script. The update() method triggers business rules to run on the same table for insert and update operations, leading to a business rule\n calling itself over and over. Changes made in before business rules are automatically saved when all before business rules are complete, and after business rules are best used for updating related, not current, objects. When a\n recursive business rule is detected, the system stops it and logs the error in the system log. However, current.update() causes system performance issues and is never necessary.

You can prevent recursive business rules by using the setWorkflow() method with the false parameter. The combination of the update() and setWorkflow() methods is only\n recommended in special circumstances where the normal before and after guidelines mentioned above do not meet your requirements.

Create a business rule

• Precedence between data lookup, assignment, and business rules

Business rules in scoped applications

Every business rule is assigned to either a private application scope or to the global\n scope.

Business rules on specific tables

Most business rules run on a specific table, which is defined in the\n Table field. You can create business rules on tables in the same scope\n and on tables that allow configuration records from another application scope.

For tables that are in a different scope than the business rule record, the types of rules are\n limited.

• Insert , Update , and\n Delete database operations. You cannot select\n Query .
• Set field values actions and scripts (the\n Script field).
• Set field values actions only. You cannot write scripts and you\n cannot abort the database transaction.
• You cannot create any other types of business rules on tables in a different scope.

Business rules on specific tables cannot be accessed by other business rules or scripts.

Global business rules

Global business rules are business rules where the Table field is set\n to Global . Global business rules may be accessible on multiple tables and\n from other scripts, depending on their scope protection. For a global business rule, define the\n scope protection by setting the Accessible from field:

• This application scope only : prevents applications in a different\n scope than the business rule from calling this business rule.
• All application scopes : allows any application to call this business rule. Note: Global business rules do not support domain separation. \n \n

Scripts in scoped business rules

When you write a script in a business rule, you can access:

• Any script includes and global business rules in the same scope as the business rule.
• Script includes and global business rules that allow applications in a different scope to\n call them. To call functions from another scope, you must specify the scope of the\n function.
• For business rules in a unique scope, you can access the scoped system APIs only.

You can create any type of business rule to run when a record is displayed, inserted,\n updated, or deleted, or when a table is queried.

• \n Navigate to All > System Definition > Business Rules . \n
• \n Click New . \n
• \n Click Submit . \n

Global variables in business rules

Predefined global variables are available for use in business rules.

Use the following predefined global variables to reference the system in a business rule\n script.

The variables current , previous , and\n g_scratchpad are global across all business rules that run for a\n transaction.

Prevent null pointer exceptions

Define variables.

User-defined variables are globally scoped by default. If a new variable is declared in an\n order 100 business rule, the business rule that runs next at order 200 also has access to\n the variable. This may introduce unexpected behavior.

To prevent such unexpected behavior, always wrap your code in a function. This protects\n your variables from conflicting with system variables or global variables in other business\n rules that are not wrapped in a function. Additionally, variables such as\n current must be available when a function is invoked in order to be\n used.

Use business rules and client scripts to control field values

Implement both business rules and client scripts for a field to enable users to set\n record values properly using both forms and lists, and to see immediate changes to the values in\n forms as edits are made.

The problem with using only a client script or a business rule to control updates to a\n field is that fields can be changed on either a form or a list. Client scripts and UI\n policies run on forms only (client-side) and do not apply to list editing. Allowing list\n editing with client scripts running on fields in a form can result in incorrect data being\n saved to the record. For systems in which client scripts or UI policies apply to forms,\n either disable list editing or create appropriate business rules or access control to\n control the setting of values in the list editor. A side effect of this is that security\n measures implemented in client scripts are easy to circumvent. The user only needs to edit\n the field in a list.

Business rules on a form are not dynamic, the user must update the record for the change to\n be seen. This makes using client scripts the preferred method for controlling field values\n on forms.

When using both a business rule and client script to control field values, the update\n behavior is the same across the system. This means that updated values are not different\n depending on whether a list of form is used to make the change. This means that the same\n functionality must be implemented twice, once in a client script and once in a business rule\n or access control.

Example: Use a business rule to create email addresses during user record\n import

An organization has a client script that sets the email address for a user to\n first.last@company.com . Administrators do this so they can see the\n email address immediately when they enter the user's information. The administrator then\n performs a bulk import of users from a spreadsheet containing the users' first and last\n names. The expectation is that each user's email address will be set automatically, as they\n are when they edit the form. Since the client script runs only on the form (the interface to\n the record), it has no effect on data imported into the record from outside that interface,\n and no email addresses are created. To solve this problem, the administrator implements a\n business rule that runs when the import occurs and creates the email addresses.

Example: Prevent list edit for a field that is not editable in the form

An organization wants to hide the Priority field on an\n incident form if the assignment group is Development . They create a\n UI policy on the incident form to do this, but their users can still see and edit the\n Priority field using the list editor. To rectify this, apply an\n access control to prevent read access to the Priority field when the\n assignment group is Development .

Using NULL as a field value

The string NULL has a particular role in scripts and is a reserved word.

The reserved word is NULL in all capital letters. A field with the value\n Null or null , for example, is acceptable. Only use\n NULL to clear out a particular field.

Any NULL field values obtained from an import set data source are inserted\n into the staging table as empty field values. You should not use the term NULL as a field value\n in import set transform maps or anywhere in the First name or\n Last name fields. Also, do not use NULL in reference fields as the system\n interprets the value as a string containing the word NULL, not as a reserved word.

Display business-rules

Display rules are processed when a user requests a record form.

The data is read from the database, display rules are executed, and the form is presented to\n the user. The current object is available and represents the record retrieved from the database.\n Any field changes are temporary since they are not yet submitted to the database. To the client,\n the form values appear to be the values from the database; there is no indication that the values\n were modified from a display rule. This is a similar concept to calculated fields.

The primary objective of display rules is to use a shared scratchpad object,\n g_scratchpad , which is also sent to the client as part of the form. This can\n be useful when you need to build client scripts that require server data that is not typically\n part of the record being displayed. In most cases, this would require a client script making a\n call back to the server. If the data can be determined prior to the form being displayed, it is\n more efficient to provide the data to the client on the initial load. The form scratchpad object\n is an empty object by default, and used only to store name:value pairs of data.

Task Active State Management business rule

This business rule determines whether the active field value needs to change based on\n changes to the State field.

The Task Active State Management business rule is executed when the\n State is changed for a task record. Its execution order is 50, and it\n runs before most other task business rules.

• If the state changes from an active state to an inactive state, the\n Active field is set to false.
• If the state changes from an inactive state to an active state, the\n Active field is set to true, effectively re-activating or re-opening\n the task.

It is recommended that you leverage the\n (current.active.changesTo([true/false]) action in your business rule, as\n opposed to creating rules on each task table that mark tasks as inactive or active.

Example business rule scripts

Find an example business rule script that helps you with a requirement of your\n organization.

Compare date fields in a business rule

It is possible to compare two date fields or two date and time fields in a business\n rule, and abort a record insert or update if they are not correct.

For example, you may want a start date to be before an end date. The following is an example\n script:

This example has been tested in global scripts, and may need changes to work in scoped\n scripts. In addition to possibly needing API changes, security is more strict in scoped\n scripts.

• u_date1 and u_date2 are the names of the two date\n fields. Replace these names with your own field names.
• The first line checks that both fields actually have a value.
• The next two lines create variables that have the dates' numerical values.
• The next two lines create different alert messages for the end user: one at the top of\n the form and one by the u_date1 field in the form.
• The last line aborts the insert or update if the date fields are not correct.

Parse XML payloads

Fields in XML format can be parsed with the system's getXMLText \n function.

returns the string 'joe'.

For information on XPATH, visit w3schools .

Abort a database action in a before business-rule

In a before business rule script, you can cancel or abort the current database action\n using the setAbortAction() method.

For example, if the before business rule is executed during an insert action, and you have a\n condition in the script that calls current.setAbortAction(true) , the new record\n stored in current is not created in the database. The business rule continues to run after\n calling setAbortAction() and all subsequent business rules will execute\n normally. Calling this method only prevents the database action from occurring.

You can use the isActionAborted() method to determine if the current\n database action (insert, update, delete) is going to be aborted.\n isActionAborted() is initialized for new threads and the\n next() method explicitly sets its value to false.

Determine the operation that triggered the business rule

You can write a script for a business rule that is triggered on more than one database\n action.

Use an OR condition in a business rule

An OR condition can be added to any query part within a business\n rule.

Reference a Glide list from a business rule

A field defined as a glide list is an array of values stored in a single\n field.

Here are some examples of how to process a glide_list field when writing business rules.\n Generally a glide_list field contains a list of reference values to other tables.

For example, the Watch list field within tasks is a glide_list\n containing references to user records.

The code below shows how to reference the field.

You can also get the display values associated with the reference values by using the\n getDisplayValue() method as shown below.

Use indexOf("searchString") to find a string in a Glide list

Use indexOf (" searchString ") to return the location of the string passed into the method if the glide list field, such as a Watch list, has at least one value in it.

If the field is empty, it returns undefined . To avoid returning an undefined value, do any of the following:

• Force the field to a string, such as: watch_list.toString().indexOf (" searchString ")
• Check for an empty Glide list field with a condition before using indexOf() , such as: \n if ( watch_list.nil() || watch_list.indexOf (" searchString ") == -1)

Lock user accounts

You can lock user accounts if the user is not active.

Default before-query business rule

You can use a query business rule that executes before a database query is\n made.

• Name: incident query
• Table: Incident
• When: before, query

The Now Platform® Washington DC release is live. Watch now!

ServiceNow Community servicenow community

• English (US)
• English (UK)
• Portuguese (Brazilian)

• ServiceNow Community
• IT Service Management
• How to Set the Incident Assignment Logic based on ...
• Subscribe to RSS Feed
• Mark Question as New
• Mark Question as Read
• Float this Question for Current User
• Printer Friendly Page

How to Set the Incident Assignment Logic based on the CI field groups

• Mark as New
• Report Inappropriate Content

‎07-30-2023 05:11 AM

Solved! Go to Solution.

‎07-30-2023 11:07 AM

View solution in original post

• All forum topics
• Previous Question
• Next Question

‎07-30-2023 05:29 AM

‎07-30-2023 09:51 AM

‎07-31-2023 12:12 AM

• Trigger approval to different groups based on value selected in a dropdown on the catalog item in ITSM forum yesterday
• Where do I use OU's created in Azure AD in ServiceNow? in ITSM forum yesterday
• How to add assignment rules to two tables of same category in servicenow in Virtual Agent forum Wednesday
• Indicators & reports for time worked in Performance Analytics forum Wednesday
• email not triggering to the user. in Virtual Agent forum Monday

Try Process AI free

How to use the script debugger in servicenow.

The Script Debugger in ServiceNow is a great tool for developers. It helps them quickly identify and fix errors in their scripts. It lets them step through code, set breakpoints, and check variables. This makes debugging much easier.

Complex scripts can be tricky to understand. Errors can be hard to find. That’s where the Script Debugger comes in! It helps you see the execution flow. You can spot bugs and any unexpected behavior.

The Script Debugger has a cool feature. You can set breakpoints. These make the script pause at certain points. You can then inspect variables to check if they are correct. This helps you catch mistakes quickly.

It also has debugging commands. You can use these to move through the code. You can execute certain lines or skip sections. This helps you understand your script better. You can find hidden issues that can cause problems.

To use the Script Debugger well, learn how to use it. Spend time getting to know its features. It’ll help your development process.

Make the most of what the Script Debugger can do. Make debugging smoother. Check variables to make sure your script is flawless. This tool will be an invaluable help!

Installing and Accessing Script Debugger in ServiceNow

Installing and using the Script Debugger in ServiceNow is a must for development. It helps developers find and fix issues quickly. Here’s a step-by-step guide on how to do it:

• Log in to your ServiceNow instance.
• Click the menu icon at the top-left corner to open the Application Navigator.
• Search for ‘Script Debugger’ and click to open.
• On the toolbar, you’ll see options like Start Debugging, Stop Debugging, and Step Over.
• Click ‘Start Debugging’ to debug a specific script.

Remember, you can set breakpoints to pause execution at certain points. This lets you analyze variables, objects, and other info, so you can troubleshoot code easily.

The Script Debugger was a great addition to ServiceNow. Before it, developers had to use manual and time-consuming debugging techniques with lots of room for error. But now, it’s easy to debug and be productive in ServiceNow.

Take advantage of the Script Debugger and unlock new possibilities in ServiceNow projects!

Navigating the Script Debugger Interface

Navigating the Script Debugger Interface:

The Script Debugger Interface in ServiceNow allows for efficient debugging of scripts. Follow the steps below to navigate the interface effectively:

• Open the Script Debugger: Access the Script Debugger by navigating to the relevant script or by using the shortcut method.
• Set Breakpoints: Identify the desired breakpoints in the script by clicking on the line numbers. This helps in suspending the script’s execution at specific points.
• Start Debugging: Execute the script in debug mode by clicking on the debug button. This allows for step-by-step execution.
• Utilize Debug Controls: Take advantage of the debug controls such as continue, step in, step over, and step out to navigate through the execution flow as needed.
• Examine Variable Values: Inspect the values of variables at any point during the script’s execution using the variable viewer. This aids in identifying and resolving issues.
• Debugging Completion: Finish debugging once the script execution is completed or when desired by using the stop button.

Additionally, leverage the debugging console to log messages and troubleshoot the script further.

Pro Tip: Utilize the Script Debugger Interface in ServiceNow to effectively analyze and resolve script issues, improving overall development efficiency.

Script debugging may seem like a daunting task, but with these features and tools, you’ll be sleuthing through your code like Sherlock Holmes (minus the pipe and deerstalker hat).

Overview of Script Debugger Features and Tools

Script Debugger is super useful! It helps programmers quickly spot and fix errors in their code. It offers a great overview of scripts, with syntax highlighting, variable values and breakpoints. It also captures runtime errors and provides helpful solutions. Plus, it includes advanced search & navigation options and performance metrics. It integrates with other dev tools and is easy to use, even for newbies.

I’ve used Script Debugger in my work and it saved me tons of time. Recently, I was able to pinpoint the exact line of code responsible for an issue with its advanced search feature. Without Script Debugger, it would’ve taken so much longer to solve this problem.

Setting Breakpoints and Debugging Scripts

Setting Breakpoints and Debugging Scripts can be a valuable tool when working with ServiceNow. By strategically inserting breakpoints and debugging scripts, developers can identify and fix issues within their code efficiently. Here’s a step-by-step guide to help you get started:

• Identify the script and the location where you want to set a breakpoint or debug. This can be done by navigating to the specific script in ServiceNow.
• Once you have identified the script, open it in the script editor. Look for the line of code where you want to set the breakpoint or start debugging.
• To set a breakpoint, simply click on the line number in the script editor where you want the execution to pause. This will allow you to inspect variables, step through the code, and analyze its behavior.

By following these steps, you can effectively set breakpoints and debug scripts in ServiceNow, allowing you to identify and fix any issues within your code efficiently.

An important thing to note is that while debugging, it is essential to pay attention to the details and variables within your script. Even a small mistake can lead to unexpected results. Take the time to thoroughly analyze and test your code to ensure it is functioning as expected.

In a similar situation, a developer was troubleshooting a complex script on ServiceNow that was causing errors in the production environment. After setting breakpoints and stepping through the code, the issue was found to be a typo in a variable name. By catching this error during the debugging process, the developer was able to quickly fix the problem and prevent further disruptions to the system.

Break up with your coding frustrations and add breakpoints to your script like a boss – because debugging deserves a standing ovation!

Step-by-Step Guide on Adding Breakpoints

Inserting breakpoints into your code is essential for debugging scripts. These breakpoints let you pause the code’s execution at certain points, so you can inspect variables, values, and behavior. Here’s a guide that will show you how to add breakpoints easily.

• Target: Before inserting breakpoints, figure out the part of the code with the issue or unexpected behavior. It could be a function, loop, or conditional statement.
• Insert: After you’ve located the code, add the breakpoint at that spot. You can do this by clicking the line number in your editor or with a shortcut.
• Run: After adding the breakpoint(s), run the script like normal. The execution will stop at the breakpoint and you can check the variables and values.

Breakpoints can do more than just pause. You can step through code line by line or continue running until another breakpoint. Take advantage of these features to get better insight into your script and detect any issues faster.

Follow this guide to add breakpoints strategically and make debugging easier. Start using breakpoints now and take control of your code!

Executing and Analyzing Scripts in Debug Mode

Set breakpoints to pause your script and analyze relevant variables. Launch your debugger tool and step through each line of code. Inspect variable values to pinpoint bugs. Make necessary changes to fix errors, testing as you go.

Remember to review error messages and consult resources. Mastering debugging gives many advantages. It enhances productivity, ensures cleaner code, and makes you a more proficient developer. Embrace debug mode and uncover the mysteries of your code!

Analyzing Script Variables and Expressions

Analyzing Script Variables and Expressions allows users to examine and understand the values and calculations within a script. By utilizing the script debugger in ServiceNow, users can gain valuable insights into how variables are being populated and expressions are being evaluated.

To visually represent the analysis of script variables and expressions, a simple and effective table can be created. The table will contain columns that provide information such as variable name, data type, and current value . This table serves as a helpful reference for developers to track and understand the variables and expressions used in their scripts.

Here is an example of how the table can be structured:

By populating the table with true and actual data, developers can easily analyze the values of their script variables and expressions. This organized and structured format eliminates confusion and provides a clear overview of the script’s functionality.

One unique detail to note is that the analysis of script variables and expressions can be an iterative process. Developers may need to refer back to this table multiple times during script execution to track changes and identify any potential issues.

Pro Tip: Utilize breakpoints within the script debugger to pause the execution at specific points and inspect the values of variables and expressions. This feature can greatly assist in identifying and resolving any errors or inconsistencies in the script.

As you analyze script variables and expressions in ServiceNow, remember to utilize the script debugger and the table structure described above for a more efficient troubleshooting process.

Don’t worry, the script debugger won’t judge your variables’ values, even if they’re as messy as your love life.

Inspecting Variable Values

Analysing script variables and expressions? One critical aspect is to inspect variable values. Knowing what values are stored in different variables during the script’s execution is useful.

Inspecting variable values gives insights into the data being processed. This lets developers spot any issues or errors and adjust the code for optimal performance.

Debugging tools from IDEs or text editors can be used to inspect variable values. Breakpoints are set to track the value of variables as the code runs. This is especially useful in complex scripts with many variables and expressions.

Console logging is another way to inspect values. console.log() can output variable values to the browser console or command line. This is great for quick debugging or monitoring during runtime.

Some scripting languages have built-in functions for inspecting values. For example, JavaScript has the typeof operator, while Python has the repr() function.

Pro Tip: Use breakpoints strategically when inspecting values to gain deeper insights into how variables change during execution.

Evaluating Expressions

Evaluating expressions is important. To do it right, precedence rules must be followed. For example, multiplication and division are done first. Knowing the data types is also key. Type coercion and conversion must be understood.

This concept has been around for centuries. Ancient mathematicians used rules and algorithms. Technology improved. It was then used in computer programming.

Now, evaluation is a fundamental part of programming. Modern languages have tools and libraries that help with complex expressions. With the right understanding, programmers can get the best results from their scripts.

Troubleshooting Common Scripting Errors

Troubleshooting common scripting errors can be a crucial step in resolving issues related to script debugging in ServiceNow. By identifying and addressing these errors, you can ensure smooth execution of scripts. Here are four points to consider:

• Identifying syntax errors: Analyzing code for syntax errors is essential in troubleshooting common scripting errors.
• Handling runtime errors: While executing scripts, it is important to efficiently handle runtime errors that may occur.
• Debugging logic errors: Debugging logic errors involves carefully examining the script’s logic to identify and rectify any flaws.
• Optimizing performance: Troubleshooting common scripting errors also includes optimizing script performance to enhance overall efficiency.

Additionally, it is vital to pay attention to other unique details that haven’t been covered yet. This may involve analyzing specific error messages, checking script dependencies, or verifying the compatibility of the script with different ServiceNow releases. Keep in mind that ensuring accurate and error-free scripts contributes to better service management.

Pro Tip: Use logging statements strategically to track the flow of the script and aid in troubleshooting common scripting errors effectively.

Watch out for syntax errors, unless you want your script to crash harder than your ex’s car after discovering your browser history.

Handling Syntax Errors

Syntax errors are a common occurrence in scripting . But, don’t worry! Here’s how to handle them:

• Identify the error by analyzing the code .
• Understand the error message and read it carefully.
• Check line by line, including special characters such as parentheses, quotation marks, and semicolons.
• Check if variable names are spelled correctly and match their usage.
• Make one change at a time and test the script after each modification.
• Remember: Paying close attention to detail and logical thinking is key!
• Also, don’t forget case sensitivity in coding languages like Python.

Identifying Runtime Errors

Runtime errors in scripting can be a pain. But, with the right approach they can be identified and fixed. Here is a 4-step guide to help you out:

• Read the error message carefully . It often has information about where it happened.
• Review the code near the error line. Look for syntax errors, brackets, and variables.
• Test inputs and outputs . See if any inputs cause runtime errors.
• Use debugging tools . These let you step through your code and check the variables.

Also, update the scripting language documentation and consult online resources.

Surprisingly, a study found that programmers spend 50% of their time identifying and fixing runtime errors!

Advanced Script Debugging Techniques

Advanced Techniques for Script Debugging

A table has been created below to outline the advanced techniques for script debugging and provide the relevant details.

These advanced techniques provide valuable insights into script execution and aid in identifying and resolving issues efficiently.

A notable fact: The script debugger in ServiceNow significantly reduces debugging time and enhances the productivity of developers.

Unless you believe in miracles, use conditional breakpoints to stop the script when your code is as confused as I am during Monday morning meetings.

Using Conditional Breakpoints

Conditional breakpoints are a powerful tool used for script debugging, which can help find and fix bugs in complex scripts. Here’s a simple 5-Step Guide for using them:

• Launch debugging environment and open desired script.
• Set a regular breakpoint at the line of code where you want the execution to pause.
• Right-click on the breakpoint marker and select “Edit Breakpoint”. Enter condition for it to trigger.
• Start debugging the script. If condition is met, execution pauses.
• Inspect variables, step through code, make changes and continue execution until issue is fixed.

Moreover, these breakpoints can be used with multiple conditions or complex logical expressions, allowing developers to spot bugs in specific scenarios. They were first introduced in Microsoft Visual Studio 2010, revolutionizing script debugging. By using conditional breakpoints, developers can speed up their debugging process and be more efficient when working with complex scripts.

Evaluating Scripts Line by Line

Script debugging is a must for programmers. A great way to do this is to evaluate scripts line by line. Examining each line helps to understand how it works with the whole script.

This technique gives a thorough view of the code and any errors or bugs. It also follows the intended logic. With this method, developers can pause the script and take a look at variables or objects. This level of control helps to pinpoint problems and make corrections.

In the past, programmers had limited resources and debugged their scripts manually. They’d print out the code and trace through it with a pen, noting any issues. While slow and labor-intensive, this method was a stepping stone for more advanced techniques, such as evaluating scripts line by line.

In summary, evaluating scripts line by line is essential for debugging. It allows developers to closely analyze their code, detect errors and make corrections. This evolution of techniques shows how programming has progressed, giving developers better tools to improve their coding.

Best Practices for Effective Script Debugging in ServiceNow

JavaScript is a must-have for ServiceNow . It helps developers write scripts and automate processes. Debugging is key to making sure the code works. Here are some tips to debug scripts in ServiceNow .

• The ServiceNow script debugger is great for debugging. It lets developers step through code line by line. Breakpoints can be set to pause code at specific points. This makes it easy to spot errors. The script debugger is like a magnifying glass for bugs.
• Console logs can also help debug scripts. Logs provide info about what’s happening in the code. By placing log statements at key locations, developers can track variable values and identify unexpected behaviors. Logs are like breadcrumbs that guide them.
• Knowing the application’s logic helps too. When developers understand how components work together, they can find errors faster. Tracing inputs and outputs between functions and modules can help pinpoint issues. Also, keep an eye out for error messages.

Debugging can be tough. There was a time when a bug was causing chaos in ServiceNow’s ticketing system. Developers searched for days until they found a missing semicolon! Hours of hard work and caffeine paid off in the end.

The script debugger in ServiceNow is useful for developers. It aids with troubleshooting and debugging , leading to faster issue resolution and improved system performance.

Developers can pause execution at specific lines with breakpoints . Inspecting variables and stepping through the code gives insight into how the script works.

The script debugger helps to track data flow within scripts. By viewing variable values during runtime, any issues or discrepancies can be identified.

Log messages can be captured with the script debugger. Log statements can be added to code and viewed while debugging. This helps understand the sequence of events and pinpoint potential areas for improvement.

Recently, a developer had a difficult issue where a business rule wasn’t working . Using the script debugger, they found a small logical error that had been missed before. The script debugger let them step through the code and look at variable values. This saved lots of time and effort that would have been used on trial-and-error fixes.

No credit card required

Your projects are processes, Take control of them today.

ServiceNow: Building Powerful Workflows by Tim Woodruff, Ashish Rudra Srivastava, Martin Wood

Get full access to ServiceNow: Building Powerful Workflows and 60K+ other titles, with a free 10-day trial of O'Reilly.

There are also live events, courses curated by job role, and more.

Debugging Business Rules

Let's turn on debugging to investigate some of the server-side scripts written earlier:

• Navigate to System Diagnostics > Session Debug > Debug Business Rules (Details) , and extra output will appear at the bottom of the screen. It shows the scripts that have been evaluated while processing that page. The detailed version of the Business Rules session debugger also shows the fields that were changed by the script.

Earlier, we made a simple Business Rule called Maintenance assignment ...

Get ServiceNow: Building Powerful Workflows now with the O’Reilly learning platform.

O’Reilly members experience books, live events, courses curated by job role, and more from O’Reilly and nearly 200 top publishers.

Don’t leave empty-handed

Get Mark Richards’s Software Architecture Patterns ebook to better understand how to design components—and how they should interact.

It’s yours, free.

Check it out now on O’Reilly

Dive in for free with a 10-day trial of the O’Reilly learning platform—then explore all the other resources our members count on to build skills and solve problems every day.

Debug Business Rules (Details)

• Select System Diagnostics > Session Debug > Debug Business Rule (Details)
• Field values set in Business Rules appear in the detailed debugging information

When detailed debugging is enabled, record field values set in Business Rules appear in the debugging output. The syntax is:

<field name>: <old value> => <new value>

In the example shown, the active field's value changed from 1 to 0.

This strategy allows you to see changed values for all fields changed by Business Rules.

Select System Security > Debugging > Stop Debugging to stop writing debugging output to forms, as the Debugger can cause performance issues in a Production instance.

results matching " "

No results matching " ".

• [email protected]
• +1(972) 469 0345

• Edge Servers
• Mission Critical Servers
• Rack Servers
• Tower Servers
• Storage Area Network
• Direct-Attached Storage
• Additional IP
• Cloud Load Balancer
• Cloud Connect
• Anti DDoS Infrastructure
• Game DDoS Protection
• SSL Gateway
• ITSM Services
• ITBM Services
• ITOM Services
• SecOps Services
• HRSD Services
• News & Events
• White Papers

How to debug the Business Rules or UI Action scripts in ServiceNow

vinay polisetti

Your browser or one of your plugins is not allowing JavaScript to be run. This is a bummer since the ServiceNow Developers Site is dynamic and depends on JavaScript to function. If you want to visit this site, please disable the plugin, activate this site for JavaScript or use another browser.

Declarative Actions in ServiceNow: The COMPLETE Guide

Declarative Actions (DA’s for short) have been around for quite a while now. Although trusty UI Actions are still going strong, and apply across all interfaces – including Next Experience-based ones, Declarative Actions are much more flexible, powerful, and can be used in many additional locations in Next Experience-based interfaces.

I’ve often found DA’s a little confusing. Part of this comes from that flexibility and power, but part also probably comes from the fact that they were originally created circa the Orlando release and originally designed for use with the legacy Agent Workspace. Since then though they have grown to primarily support and work with new Next Experience-based interfaces.

This article focuses exclusively on Declarative Actions as they work with new Next Experience-based interfaces; think anything created or editable in UI Builder – like CSM Configurable Workspace, or Service Operations Workspace.

There are a few tables and other aspects of DA’s that apply only to the legacy Agent Workspace. I have intentionally omitted these for simplicity as it is unlikely going forward you’ll need to do much with these.

With more-and-more Next Experience-based UI’s being released, I decided recently to deep-dive into DA’s to fully understand how they work, and to be able to share my learnings. Although there are a lot of guides out there, there was nothing totally comprehensive which entirely completed the puzzle for me. I hope this article will complete the puzzle for you.

Declarative Action Basics

What are declarative actions.

Think of Declarative Actions as an upgrade to UI Actions .

UI Actions have been around forever in ServiceNow and let users perform actions from lists and forms. Furthermore, they allow developers and admins to define new actions so they can tailor the way that out-of-box lists and forms work without editing their UI code.

Historically, ServiceNow was all about lists and forms in the Core UI. That meant users mainly interacted with lists of records – like a list of incidents. When the user clicked on a record in a list they were taken to a detailed form view of that record. UI Actions were designed for UI’s based around this paradigm. There was also the occasional “workbench” interface, however those were entirely bespoke and rigid and didn’t offer a standard way to add elements to the interface.

Admins could add UI Actions to the top or bottom of a form, and adjust how they’re presented to users – for example, as a link, or within a menu. They could also do the same at the top or bottom of a list, and have users take action on many records at a time.

But things are changing. There are many new Next Experience-based UIs like Workspaces, Playbooks, and Catalog Wizards. Plus, users can build their own custom Next Experience-based UIs. UI Actions don’t work well with these new types of UIs because they’re so heavily based around the concept of lists and forms.

That’s where Declarative Actions come in. They’re more flexible and work with any style of UI, whether it be a list, or a form, or a playbook, or a catalog wizard. They are the future of performing actions in ServiceNow.

It’s important to stress though that UI Actions still have their place. While you can do everything that UI Actions do with Declarative Actions in Next Experience-based UI’s, Declarative Actions don’t work in the Core UI.

This means for example if you want to create an “Assign to Me” button on the Incident incident table, if you did that with Declarative Actions that button would only appear when viewed through a Next Experience-based UI – it wouldn’t appear in the Core UI.

This might be fine – your users might solely be using the Next Experience-based UI, and will never use the Core UI. However if you want parity of functionality between the two interfaces, it’s still worth leveraging UI Actions, and they can work in harmony on lists and forms. Some Next Experience components like the Action Bar have functionality to display UI Actions alongside Declarative Actions.

What Types Are There?

While UI Actions only support lists and forms, DA’s are designed with much more flexibility and thus can support many places in the interface that one may want to add actions to.

As of writing the following DA types exist, which display in the areas of the interface as noted.

When developers at ServiceNow are building out-of-box components they can enable them to support DA’s. This means that as new components and interfaces are developed and released there is the possibility that even more types will become available.

In most cases there’s a 1-to-1 relationship between a component which supports DA’s, and a DA type. For example, List -type DA’s always appear in the List component. However there are other cases where a single component supports multiple different types of DA. For example the Playbook component can have Playbook , Playbook Stage and Playbook Card -type DA’s appear in it.

Each of these different types of a DA can be found in the Action Model Definitions sys_declarative_action_model_definition table.

What Can They Do?

Executing a DA is usually done by clicking on it – for example, clicking on a button. What path the execution of a DA follows when it is executed is referred to as how it is “implemented”.

There are three different ways a DA can be implemented in Next Experience-based interfaces:

• Client Script – to execute a UI Action-style script on the client-side .
• Server Script – to execute a UI Action-style script on the server-side .
• UXF Client Action – to dispatch an action in a Next Experience-based UI for handling by an event handler in UI Builder.

There are other ways a DA can be implemented, however they are only relevant to the legacy Agent Workspace interface and so I’ve intentionally omitted them from this article

An example scenario of a DA implemented as a Client Script might be where you want some kind of browser action to be performed – like each of the items selected in a list to be opened in a new browser tab, a web request to be made to determine a value for a field, or some kind of interaction with the GlideForm or GlideList API’s.

An example scenario for a DA implemented as a Server Script on the other hand might be where you want to add an “Approve” button at the top of a form to update a related approval record. Because it’s a related record you’re updating, the GlideForm API won’t really be useful (as it only knows about the current record). This action requires some additional queries of the approval table, and that is usually best done on the server-side.

The Server Script and Client Script implementation types should be very familiar and easy to understand coming from the world of UI Actions. Similar to UI Actions, deciding whether to choose to implement your DA as a Server Script or a Client Script is really up to you and the considerations of your use case.

DA’s implemented as a UXF Client Action however are very different to the world of UI Actions. What can be done with these is very much down to the page that they are appearing on as they simply dispatch actions with a payload, and those actions need to be handled by the UI Builder page itself.

For example, a record page might have an event handler on it to support opening a record’s form in a sub-tab, or in a modal dialog. An extreme example might be a podcast player page that has an event listener to allow a specified audio file to be started playing from a certain point. It’s really up to what the page and it’s event handlers allow to be done – and don’t worry, I’ll be covering event handlers later in this article.

It’s worth noting that although the execution of a Client Script and UXF Client Action starts on the client-side, that doesn’t mean they can’t trigger something to happen on the server-side as well. This could be done in a Client Script through a GlideAJAX request, or in a UXF Client Action through the event hander triggering the execution or refresh of a data resource.

Who Creates Them?

There are three different personas that have a role in the creation of Declarative Actions and determining what they have the capacity to do.

Component Author

Developers at ServiceNow create the components that DA’s can be presented inside. They also determine what type of DA’s will show up in their components (creating new Action Model Definitions if necessary), and what contextual data can be passed along from the component to the DA. Let’s call this persona the Component Author .

Page Author

Whether they be the developers of ServiceNow, or partners, or customers, the Page Author persona creates pages in UI Builder that leverage DA-enabled components. For example, a Page Author might create a record page that has the Action Bar component on it, which hosts Form -type DA’s.

The Page Author will also build into their pages capabilities that they want to allow be triggered by DA’s implemented as UXF Client Actions . For example, they can ensure an event handler is setup on their page so that DA’s can trigger a modal to open, or for a specific tab in the sidebar to be selected, or a specified audio file to start playing.

For those capabilities they build into the page they also know exactly what data is required by them. In the case of the modal, perhaps they built some kind of behaviour to automatically close the modal after a set number of seconds and they want to allow DA’s to specify that timeout value. The Page Author can create payload records to do this, which will help Declarative Action Authors by giving them a template to start from when defining the data that will be provided by their Declarative Action – and don’t worry, I’ll be covering payloads later in this article.

Declarative Action Author

As with UI Actions, the whole point of Declarative Actions is to allow additional functionality to be added by developers and admins without requiring they edit the code of the UI itself. This means developers and admins shouldn’t need to make changes to a page to be able to add actions to it. Making changes to a page not only requires edit access (which even admins may not have the rights to) but also makes upgrades harder, and so this architecture principle of Declarative Actions is a good one.

When developers and admins are defining DA’s and placing them on specific parts of the UI, they are taking on the role of the Declarative Action Author .

The Page Author and the Declarative Action Author may in some cases actually be the same person. For example, what’s the point of a Page Author creating a record page with no actions able to be performed on it out-of-box? They will likely of course want to create some DA’s that come out-of-box with their page (such as a “Save” button). In this case they will be performing the role of both the Page Author and the Declarative Action Author .

However, later on another developer or admin can come along and take on just the role of Declarative Action Author by adding their own Declarative Actions to that page – without requiring the page to be edited and therefore not requiring taking on the role of a Page Author as well.

For DA’s implemented as a UXF Client Script , what the Declarative Action Author can do is limited by what the Page Author has already done on the page. For example, the Declarative Action Author cannot create a DA which performs an action if the Page Author hasn’t created a page which allows for that action to happen.

Giving Declarative Actions Context

A Declarative Action being provided with context is critical to ensure that it can perform useful operations. For example, in the earlier scenario of an “Open in new tab” button at the top of a list, what use would it be if it didn’t know which of the items in the list were selected?

In the case of a DA implemented as a Server Script or Client Script , this context is provided to those scripts in the same ways that UI Actions are – via the current object (and in some situations the parent object) in the case of a Server Script , or the GlideForm and GlideList API’s in the case of a Client Script .

However on the client-side, DA’s have a lot of additional functionality when it comes to context. This makes sense because the GlideList and GlideForm API’s are predictably very list and form based API’s, and additional context is needed with the expanded types such as Playbook Card or EVAM that DA’s offer.

Each DA type has different contextual data that can be provided to it on the client-side. It makes sense that a List -type DA would be provided with context about what records in the list are selected, but it doesn’t make sense that a Form -type DA would be given that same context.

Some other examples of useful context:

• A Field -type DA appears as a button next to a field. The name of the field, its current value, and the table and sys ID of the record that the user is viewing that field on would all be useful contextual data to have.
• A Playbook Card -type DA can appear as a button at the bottom of a card that represents an activity in a process. The name of the activity, the associated record’s table and sys ID, and the status of the activity would all be useful contextual data to have.

Definitions of this contextual data are stored in the Action Model Fields sys_declarative_action_model_field table, which is directly related to the previously mentioned Action Model Definitions table that stores the core DA types.

The Action Model Fields table is also shown as a related list on the Action Model Definition form, allowing you to see exactly what contextual data is available to each DA type.

It’s important to understand that this additional contextual data is not available to the “script” fields of DA’s implemented as a Client Script or Server Script . These both operate in the same way as UI Actions, with context supplied through current  (and in some situations parent ) on the server-side, and GlideList and GlideForm API’s on the client-side.

However the additional contextual data is available to the Client Conditions and Scripted Client Conditions fields of all DA’s regardless of how they are implemented, so it certainly can have some use for all implementation types. It’s primarily useful for DA’s implemented as a UXF Client Action though as you will see later on in this article.

Pre-Prepared Payloads

As mentioned earlier, a task that the Page Author needs to do when creating a page in UI Builder is to hook up event handlers to determine what capabilities the page has that Declarative Action Authors can leverage for their DA’s which are implemented as a UXF Client Action . I’ll cover later in this article how this is done, however what these actions are is of course not static across all pages but is instead determined by the page itself and what its purpose is.

Some examples might be that a record page requires the ability to open another record in a sub-tab, or open a modal, and for an extreme example a podcast player page would need the ability to start an audio file playing.

Each of these different actions that can be performed on the page requires different data to be sent to it. Navigating to another record would require the table name and the sys ID of the record to navigate to. For an action that plays an audio file, you’d probably need to supply the URL of the audio file, and perhaps a timecode for where in the audio file to start playing from.

Because these actions on a page are defined and controlled by the Page Author , that persona is also best placed to create Action Payload Definitions sys_declarative_action_payload_definition . These are essentially pre-prepared templates of the data that’s expected to be sent to the event handler on the UI Builder page. It’s in this table that you define the models that the payload supports, as well as a template of the payload in JSON object format.

For example, in the scenario where a Page Author is creating a podcast player page, the action which plays the audio file might have in the payload field of its Action Payload Definition the following:

The purpose of each of the properties here should be self-explanatory based on their name, however their values are worth noting.

• The audioFileUrl property has an empty value, meaning that unless the Declarative Action Author overrides it when they use this payload, this property on the payload will be an empty string.
• The startAtTime has a value of 00:00:00 . This will be the default value, but again the Declarative Action Author can override it if they want to.
• The episodeId property has a value of {{sysId}} . Being in double-curly braces makes this a placeholder for contextual data from the DA type. For example, a Form -type DA has an Action Model Field with the name sysId , so if this payload were used in a DA in the Action Bar this placeholder would be replaced by the sys ID of the record being viewed. Again, this will just be the default value and it can be overridden by the Declarative Action Author if they want.

You will notice various Action Model Field records of type “Data Object” and “JSON”. An example of these is variables on the Catalog Wizard type, and currentUser on the Form type. These you are able to dot-walk with, so for example if you had a variable called ordered_by appearing in the catalog wizard, you could access it by using the {{variables.ordered_by}} placeholder.

Upon creating an Action Payload Definition record, the different properties of the JSON in the payload field will be automatically extracted and for each of them a record in the Action Payload Fields sys_declarative_action_payload_field table will be created.

This table can mostly be ignored as it is used simply to power interfaces you’ll see later on to override the template values within the JSON template when a Declarative Action Author is actually creating a DA.

For each model the payload supports, a record in the Action Payload Mapping sys_declarative_action_payload_mapping table will also be created.

Again, this table can be ignored as it doesn’t seem to serve any purpose other than perhaps assisting with the back-end functioning of the DA configuration and runtime behaviour of which Page Authors and Declarative Action Authors do not need to be concerned with.

Creating & Assigning Declarative Actions

The core table at the heart of the Declarative Actions concept is the Action Assignment sys_declarative_action_assignment table. This is the place that Declarative Action Authors will create actual DA’s and set their core attributes such as:

• The model of the DA – i.e. the type of their DA e.g Form , Field , Playbook Card etc.
• The label – i.e. what text appears on the button.
• The conditions for it appearing – what types of records should it appear on, for which roles.
• How it is implemented – i.e. Client Script , Server Script , or UXF Client Action .

The table name Action Assignment being the place to create DA’s may be a little confusing, especially since there’s an Action Definitions sys_declarative_action_definition table and the term “definitions” is used elsewhere in the DA data model to be the place where you create/define things.

However, this Action Definitions table is only relevant to how DA’s appear in the legacy Agent Workspace and is not involved in any way for Next Experience-based interfaces so it is safe to ignore it and consider the Action Assignment table as being the core table for creating/defining DA’s.

For Vancouver-and-earlier releases of ServiceNow it’s important to never visit the Action Assignment table directly when creating new DA’s. This is because the Model field on the Action Assignment form (where the type of DA is set) is hidden by default and set automatically depending on the module and list you navigated to the form through.

When creating a DA you should thus navigate to the table via the relevant module in the Application Navigator for that type and then press the New button on that list. These are as follows:

Depending on the type of DA and how it is implemented, there will be various additional things to configure via this record. For example, for Field -type DA’s, what types of fields or specific fields should it appear on and what icon should appear on the button? For DA’s implemented as a UXF Client Action , what is the Action Payload Definition that should be dispatched when the button is pressed?

Furthermore, in addition to the configuration options directly on the Action Assignment record there are also a number of related tables that that control how and under what scenarios a DA of certain types appear & behave.

These supplementary tables only really need to be worried about if you are dealing with a DA of the relevant types listed in the table above. Each of them have their own use case related configuration, for example for the UX Form Layout-related tables these allow UI Actions and Declarative Actions to be positioned alongside each other, and control the visibility of these items for different users and groups.

Handling the Action

Now that we’ve covered what needs to be done to get a Declarative Action to display, the equally important task of course is setting what happens when the Declarative Action is triggered. As previously mentioned, the “Implemented as” field of the Action Assignment record will determine this, but let’s go into detail on how the different implementation methods work in further detail.

Client Script & Server Script

Selecting that a DA is implemented as a Client Script or Server Script will reveal the relevant script field on the form. The scripting environment here is almost exactly like the relevant UI Action type, with context supplied through current  (and in some situations parent ) on the server-side, and GlideList and GlideForm API’s on the client-side.

This is quite a simple concept, as triggering the Declarative Action just runs a script, and that script operates in a way that anyone used to server-side and client-side UI Actions should be familiar with.

UXF Client Action

A much more new concept though is the way that a DA that’s implemented as a UXF Client Action works.

The Action Payload Definition selected on the Action Assignment record via its Specify client action field will generate the structure of the JSON payload of the action. Let’s reuse the example from before of the action that plays an audio file:

The default values of that payload will be used, and any placeholders will be replaced with the contextual data of the Action Model Field with that name for the relevant Action Model Definition .

For example, if we used that Action Payload Definition for a DA appearing in an Action Bar component, it might end up like this:

Notice that the {{sysId}} placeholder has been replaced by the actual sys ID of the record.

With the payload generated, it can be overridden on a per- Action Assignment basis using the Payload Map field on the Action Assignment record.

For example, we could select audioFileUrl from the dropdown, and set its value to be the URL of an MP3 file, and do the same for startAtTime and set its value to be 00:01:00 .

Doing so would give us a payload like this:

Notice that the episodeId property is still on the JSON. This is because the Payload Map field is overriding the values, rather than creating a whole new payload.

We also have still have access to the values from the Action Model Fields in the Payload Map here too, and we can use the same double-curly bracket notation to refer to these fields, for example: {{isNewRecord}} . Helpfully, the Action Model Fields available for that particular DA type will be shown in a related list at the bottom of the form, allowing easy reference to the contextual data available when using double-curly brackets.

To illustrate how this payload is built you can refer to the following diagram:

Add-on Event Mappings

So where does the payload actually go? How does it influence and cause something to actually happen on a Next Experience-based interface like a specific modal dialog appearing, or a specific audio file to start playing at a specific point. That’s where the UX Add-on Event Mapping sys_ux_addon_event_mapping table comes in.

UX Add-on Event Mapping records are for a Declarative Action Author to explicitly say that for a certain instance of a component on a specific variant of a page, which of the handled events on a that page should be dispatched when a specific Declarative Action is triggered.

There are 5 fields on this table that are crucial for these records:

• Source Declarative Action – the Declarative Action being being triggered (i.e. the Action Assignment ).

• Target Payload Mapping – instructions for how the payload of the Declarative Action is mapped onto the properties of the handled event on the page. For example, the payload’s episodeId property might be mapped onto the idOfEpisodeToPlay property of the handled event being targeted.

While the first 4 fields are pretty easy to understand, the Target Payload Mapping field looks a little scary, right? Thankfully, in UI Builder there’s a UI that assists with creating and modifying UX Add-on Event Mapping records.

If you open the page that you want to hook your Declarative Action up to you can select from the content panel the e.g. a List component, and then in the configuration panel on the Config tab, at the bottom you’ll see a link labelled Configure declarative action mappings .

When you click it, a modal dialog will appear allowing you to create and edit UX Add-on Event Mapping records.

Because you’re on a specific page, and you clicked a specific component on it, that informs the values of the Parent Macroponent and Source element ID fields. The panel on the left lets you see which Declarative Actions could be dispatched by this component, and allows you to choose the relevant one to be the Source Declarative Action .

The dropdown in the middle allows you to select which handled event of the page is the Target event , and finally the fields below that allow you to use a regular UI Builder binding scheme to easily create the JSON that will be put into the Target Payload Mapping field. For example, to map a payload’s episodeId property onto an idOfEpisodeToPlay property of a target handled event, you would see a field here called something like “ID of Episode to Play” (or whatever the label of the idOfEpisodeToPlay property is) and you would set that to @payload.episodeId – @payload in this case is referring to the payload of the Declarative Action.

Handled Events

While the Declarative Action Author is creating Declarative Actions and mapping those actions to handled events on the page, the Page Author is responsible for the page itself, what events it handles, and what happens when those handled events occur.

UX Add-on Event Mapping records can only be associated with events that are listed in the Handled Events field of the macroponent of the page variant. This can be viewed from the UX Macroponent Definition record itself:

Handled events are UX Event sys_ux_event records and can be created directly in that table themselves, then manually associated with the page via this Handled Events field.

Handled events can also be viewed directly in UI Builder by selecting Body from the content panel , and in the Events tab of the configuration panel scrolling to the bottom to see the Handled events section:

From the Handled events section you can edit existing handled events, or define new handled events.

The above creates and/or associates a handled event with the page, and once that’s done the Page Author can specify what happens when those handled events occur.

Scrolling to the top of the Events tab of the configuration panel , with the handled event now associated with the page we will be able to create event mappings for it. If we click the + Add event mapping button the handled event will appear in the dropdown list.

Clicking it will make that event appear in its own section, and we can click the Add event handler link to open up the event mapping dialog to do things like link to a particular destination, open a modal, perform operations on a data resource, or anything else that can be done in UI Builder via events.

To illustrate the way this is set up, please refer to the following diagram:

As mentioned in the section about personas, a Page Author is likely to be creating these event mappings on the page first – e.g. open a modal dialog, or start playing an audio file. Then at a later date a Declarative Action Author will come along and create their Declarative Actions, and map them to the handled events of the page.

Declarative Action Cheatsheet

Instead of having to read this article every time you want a refresher on Declarative Actions in ServiceNow, I created this handy single page cheatsheet to describe what the purpose of each table is, its relationship to other tables, and the general persona responsibilities for the tables. It also covers some tips on event dispatch and handling, and the configuration interfaces available in UI Builder.

Sample Application

I’ve published a sample application to Github to show examples of what these various Declarative Actions look like when setup. You can find it on Github at dylanlindgren/declarative-actions-demo . If you fork the repo into your own Github account you will be able to import the fork of the repo into your instance using ServiceNow Studio .

I hope this article has helped you to understand Declarative Actions in ServiceNow.

Please leave a comment below if you have any feedback on this article, and follow me on X at x.com/dylanlindgren to keep in touch!