UI and Data policies

Ganesh Pardhe · ‎09-24-2020

Hello Developers,

Please find below article to understand the basics about UI and Data policies.

UI and Data Policies

UI Policies and Data Policies can help to prevent users from accidentally (or intentionally!) making certain changes in our database, given a set of conditions. These policies may be client-side, or they may be server-side, meaning that they may disable or make mandatory, certain UI elements in the user's browser, or they may enforce certain rules on the server.

In this chapter, we'll learn about:

UI Policies
Catalog UI Policies
Scripting in UI Policies
The Reverse if false functionality
UI Policy Actions
UI Policy Order
Data Policies
Data Policies vs ACLs
Converting a Data Policy to a UI Policy

UI Policies
UI Policies are a user-friendly way to control whether fields on a form are mandatory, read-only, or even whether they're visible. The UI Policy record itself, which resides in the UI Policy[sys_ui_policy] table, consists of a set of conditions, a short description, a relationship to another record or set of records, and a few other odds and ends. It does not however, contain information on the action to be performed:
UI Policy Actionsare stored separately, in the UI Policy Action [sys_ui_policy_action] They are related to the UI Policy via a reference field, which - as we discussed in a previous chapter - means that they can (and by default, do) show up in a related list at the bottom of the UI Policy form:
These UI Policy Actions consist of a reference to the field to which the action applies, and drop-downs indicating whether the field should be Visible, Mandatory, or Read-Only.Each field has three options: True, False, and Leave Alone. As you might imagine, creating a UI Policy Action where the Read-Only drop-down is set to True, will make the field to which it applies, true. This will only apply on the table to which the parent UI Policy applies. Further, unless the Global tick-box is checked on the parent UI Policy (which it is, by default), it will only apply to the view specified on the parent UI Policy:
In order for a UI Policy Action to apply to a given field (or in the case of catalog UI Policy Actions, a given variable), it must appear on the form in question. The same is true if the field is used as part of a Condition. Even if the field is not visible, it must be included on the form in order to be evaluated as part of a policy condition, or set as part of a policy action.

Catalog UI Policies

Catalog UI Policies are very similar to regular UI policies, except for a few key details. Catalog UI Policies are stored within the Catalog UI Policy [catalog_ui_policy] table, as opposed to the UI Policy [sys_ui_policy] table. Also, rather than choosing a table on which to apply the policy actions, Catalog UI Policies are configured to run on either a given variable set (which may be found in multiple catalog items), or on a specific catalog item:

A catalog UI policy can only reference variables that are associated with the catalog item or variable set to which it applies. Just like UI Policies, Catalog UI Policies can only evaluate conditions and perform actions based on variable fields which exist on the form (even if they're hidden at all times).

As you might have guessed, Catalog UI Policy Actions are also stored in a different table from UI Policy Actions: The Catalog UI Policy Action [catalog_ui_policy_action] table.

Reverse if False

The Reverse if False tick-box (which is only available on the Advanced view of the UI Policy and Catalog UI Policy forms), allows us to specify whether the UI Policy Actions (or Catalog UI Policy Actions) associated with our UI/Catalog UI Policy have their actions reversed whenever the Condition associated with their parent policy does not evaluate to true.

For example, imagine we have a condition [Assigned to][is][empty] on a UI Policy. When met, a UI Policy Action is triggered, which sets the Assignment group field to Mandatory. This way, if we don't have an assigned user, at least we can be sure we have an assigned group.

In this scenario, if we have Reverse if False enabled, then as soon as the assignment group field contains a value, then not only is the UI Policy Action which made Assignment group read-only no longer applicable, but another action with the opposite effect is fired, actively setting the Assignment group field to non-mandatory. This applies even if the field is made mandatory by another means; and this is where Order comes into play. More on order and how to create robust policies that do not conflict, later in this chapter.

As you can imagine, Reverse if False can be an extremely powerful and useful tool, but it can also be the source of a great deal of confusion, if it behavior is not well understood in the context of all of the UI Policies and Client Scripts that might run on a given record or form. It is not necessary, and not recommended, to set a field to Read-Only = False if that field is not normally read-only. Only if you need to alter some behavior, should the field's properties be set by a UI Policy; otherwise, the Leave Alone option should be selected. Leave Alone does not result in any action, which means that there's nothing to reverse in the event that the condition on the policy is not met.

There are a few circumstances where Reverse if False should not be used, but the vast majority of UI and Catalog UI Policies leave this option enabled. It is usually only used when you have one UI Policy controlling the behavior of a given field or set of fields under one condition, and a separate UI Policy controlling their behavior under the exact opposite condition. In a situation like this, it's important to be careful not to modify one of the policies without modifying the other to match, or you could end up with aberrant behavior.

If the condition on a UI policy returns false, then one of two things might happen:

If the Reverse if false tick-box is selected, then the opposite of the UI Policy Actions are enforced. For example, if a UI Policy Action sets the Short Description field to visible when the conditions are matched, then having Reverse if False enabled would make it so that the short description field is hidden when the condition is not matched.
If Reverse if false is not selected, then the UI Policy simply does nothing.
This does not mean that the UI Policy Actions are undone. Say for example, that you have a UI Policy which causes the Work Notes field to become mandatory when the State field is set to Closed, but the Reverse if false tick-box is unchecked. In this case, if the user set the State field to Closed, then Work Notes will become mandatory. However, if the user then changes their mind and sets the State field to another state such as Work in progress, then the Work Notes field will remain mandatory.

Scripting in UI Policies

UI Policy conditions are evaluated both on-load (if the On Load tick-box is selected on the Advanced view) and whenever an update is made to any field on a form in ServiceNow. When an update is made, the condition on the UI Policy is re-evaluated. If the condition returns true, then the UI Policy Actions run. If the conditions return false (and Reverse if false is enabled) then the opposite of the UI Policy Actions run.

Understanding that these events all happen within the browser (AKA the client) tells us that UI Policies are evaluated client-side. In the Advanced view of the UI Policy form, there is a Script section. In this section, if the Run Scripts tick-box is selected, two script input fields will be displayed: Execute if true, and Execute if false. Each script has a pre-defined default value, which acts as the scaffolding for the script:

function onCondition() {

}

Any code you write inside of that function will be executed client-side, and thus will have access to the same APIs as any client script. Using these script fields, you can define both functionality, and additional logic for checking more complex conditions. We'll learn all about client scripts and the client-side APIs that we can access in a later chapter on client scripting.

UI Policy Order

The Order field on UI Policies is very important to how UI Policy Actions are processed. When two UI Policies contain a UI Policy Action that acts upon the same field - even if they act upon different properties of that field (visible vs. read-only, for example) - they can potentially conflict. Conflicting UI Policy Actions will be shown in the related list on the UI Policy, with a red dot indicating the issue:

If you open the Action, you'll be presented with an error message indicating that the run order of the UI Policy Actions is unpredictable.

This warning will only occur when the Order field on the parent UI Policy is set the same on both. UI Policies execute in the other indicated by the Order field, starting with one. The higher the value, the later it executes. This also means that a higher value in the Order field means that the policy will take priority over others with a lower Order value. It won't undo any actions performed by lower-Order Policies, but it will overwrite them.

The default value of the Order field is 100. As with most numerical fields, it is generally a good idea to put some space in when you use a different Order value for another record. For example, if we wanted to add in another UI Policy that would take priority over this one, we might choose an Order value of 200 or so. That way, if we later decided that we wanted one or more other Policies to slot in between them, operationally speaking, we could use values like 125, 150, and 175, with plenty of room in-between.

Another example of when this is a good idea, is the State field on Task records. Since State is technically an Integer field (each value such as New, Work in Progress, Closed Complete, and so on. Corresponds to an integer), it's a good idea to put some space between the previous and next numbers whenever you create a new State option. It's always best to think ahead in situations like this, and "future you" will appreciate your precautions.

Demo

Let's explore UI Policies in a less abstract fashion: by creating one! Let's create a UI Policy so that if and when the Major Incident field in our Virtual War Room records is populated, it'll be read-only. This way, a user can't create a Virtual War Room for one incident, and then switch it to another.

To start off, navigate to the Virtual War Room table by typing u_virtual_war_room.list into the application navigator filter bar, and pressing Enter.
On the list view of that table, click on the hamburger menu at the top-left, then click Configure, then UI Policies. On the UI Policies list, click New to create a new UI Policy on the Virtual War Rooms table. The Table field will be auto-populated with our Virtual War Room [u_virtual_war_room].

Note that these instructions are for List V3. If you have List V2, you'll be able to access UI Policies by right-clicking on the list header, and mousing over Configure, then clicking UI Policies.

Set the Short description field to something descriptive, like Make incident field read-only when populated.
Add one condition to the Conditions field: [Major Incident][is not empty]. Then, right-click in the form header, and click Save to save the record to the database and display the UI Policy Actions related list.
At the top of the UI Policy Actions related list, click on New. On the corresponding form, set the Field name field to Major incident.
Set the Read only field to True, but leave the Mandatory and Visible fields set to Leave alone. Finally, click on Submit.

Now if you visit or create a virtual war room ticket with the Major incident field filled out, that field will be read-only; however, if you create a new Virtual War Room ticket from the list view without the Major incident field populated, you'll notice that the field is editable, because it doesn't yet meet the criteria specified in our UI Policy!

Data Policies

Data Policies, unlike UI Policies, execute on the server. They are closely linked to UI Policies in terms of behavior and functionality. They can even be "used as" UI Policies on the client, when implemented (however, with limited functionality). Strangely, Data Policies reside in the sys_data_policy2 table. That 2 is not a typo; it has been that way at least as far back as Eureka.

Data Policies allow you to prevent certain changes on the server, by rejecting database updates that don't fit the criteria laid out in the data policy. You can either prevent edits by making a field read only, or you can require a field value by making a field Mandatory, using a Data Policy rule.

While Data Policies can be used as UI Policies on the form, they do not have the exact same functionality as a UI Policy. You cannot, for example, make a field visible or hidden using data policies, because there is no server-side equivalent of a contextually hidden field. There is also no Advanced view, no scripted conditions, and no UI or server-side scripting possible through a data policy (except to the extent that scripting is possible inside of any condition builder to make a determination about whether the data policy should run).

Data Policies do however, have Reverse if false functionality. This applies to both the server-side actions, and the effective UI Policy on the form, if that is enabled.

Demo

As with UI Policies, let's explore Data Policies in ServiceNow by creating one! Let's create a UI Policy that prevents users from re-opening a virtual war room, once it's closed:

Navigate to the Virtual War Room table that we created in an earlier chapter, and click on the hamburger menu at the top-left. Choose Configure, and then click on Data Policies.
On the Data Policies list, click the blue New button at the top-left to create a new Data Policy record. The Table field will automatically be set to the Virtual War Room [u_virtual_war_room] table.
On the Data Policy form, set the Short Description to Prevent re-opening War Rooms, and ensure that Use as UI Policy on Client is checked.
Add a condition to the Condition field that contains: [State] [is one of] [ClosedComplete, ClosedIncomplete, ClosedSkipped]. Include any other "closed" states in your instance, if you have any:

Right-click on the form header, and click on Saveto save the record and reload the form without returning you to the previous page. This step, saving the record to the database and thus assigning it a Sys ID, causes the related list Data Policy Rules to render.

In the Data Policy Rules related list, click on the blue New button. The Table field should again be automatically populated.

In the Field name field, select State. Set the Read Only field to True, but leave Mandatory as Leave alone. Then, click Submit. This will return you to the Data Policy record.

Now, if you set the State field on a Virtual War Room record to a Closed state, it will turn the field to read-only because the Use as UI Policy on client field was set to true. If we didn't have that field set to true, then the field would not appear to be read-only on the client, but once a record was saved with a Closed state value, if you tried to re-open it and save it again, you would receive an error in the client that said Invalid update, and another error with a Data Policy Exception.

You might be thinking: Why not just use a UI Policy to prevent this change?

This is a legitimate question. The answer is that UI Policies only execute on the client, and only inside of the user's browser. This means that any sufficiently clever user can bypass UI Policies, but it also means that any alternative method of making a change to the database (such as via a script, a web services API, or even editing a field in the list view) can bypass this protection.

Data Policies have a unique place and purpose within ServiceNow, just like UI Policies and ACLs each have their own place.

Converting between Data and UI Policies

It's often possible to convert a UI Policy to a Data Policy, and vice versa. On the UI Policy form, you'll find a UI Action called convert this to Data Policy.

This UI Action will only show up if the following criteria are met:

The Run Scripts tick-box on the Advanced view must not be checked.
The Global tick-box must be checked.
Any UI Policy Actions associated with the UI Policy must not affect the visibility of a field (all Actions must have the Visible field set to Leave alone).

If the above conditions are met, you'll see the Convert this to Data Policy UI Action under the Related Links section of the form.

Clicking this link will automatically generate a new Data Policy and take you to the form displaying the new record. At the bottom, you'll also see auto-generated Data Policy Rules in the related list.

Demo

Let's navigate back to the UI Policy we created earlier to ensure that the Major Incident field on the Virtual War Room table becomes read-only once it's populated. You can find it by going to System UI | UI Policies from the Application Navigator.

If you don't see the Updated column in the list, add it by clicking on the Personalize List gear icon at the top-left of the list, and add it.

Once it's on the list view, sort the list by most recently updated, and the UI Policy we created earlier in this chapter should show up near the top. Click on the name in the left column to open the UI Policy.

Near the bottom, above the UI Policy Actions related list, there is a form section labeled Related Links. Under this section, you should see a link called Convert this to Data Policy, since our UI Policy meets the conditions defined in the section above for converting to Data Policy. Clicking on this link will deactivate the UI Policy, and take you to a pre-made Data Policy, with Data Policy Rules corresponding to the UI Policy Actions that were associated with the deactivated UI Policy.

Data Policies versus ACLs

Data Policies are an effective means of controlling a few fields, and is probably the best way to ensure that a field has a value on the server before a record can be inserted or updated. When it comes to ensuring that a field (or a table) is fully inaccessible to users without a certain role however, ACLs are the way to go.

ACLs, short for Access Control Lists and otherwise known as Security Rules, are another means by which you can control access to elements within ServiceNow. They can serve much the same function as Data Policies, and a great deal more. One major difference between Data Policies and ACLs, is that ACLs are scriptable. This allows for a great degree of flexibility of functionality. ACLs

You can access the list of ACLs on a given table in the same way you'd access many other customizations: either by right-clicking the form header, or through the hamburger menu at the top-left of the list view, and then clicking on Customize, and then Security Rules. However, modifying Security Rules requires permissions elevation on instances running the high security plugin. On such instances, you can elevate permissions by left-clicking your profile link, and clicking Elevate Roles.

ACLs operate on a table-and-field basis, but wildcards are accepted as a replacement for either. An ACL can be a table ACL that grants or restricts access to an entire table, or a field ACL which grants or restricts access to one or all fields on a table. For example, the incident.* ACL would grant or restrict access to all fields on the incident table, but a user must also have access to the table itself. That ACL would have a name like, simply, incident.

Here is an example ACL that prevents modification (Write) on any field in the virtual war room table, once a war room record has been closed.

Keep in mind that when an ACL prevents write access to a field, but not read access, it shows on the form as a read-only field, even when not made read only by any Client Script or UI Policy.

Best practice when it comes to security, is to always assign roles to groups; not directly to users. Once a group contains the roles you'd like to assign, add users to that group. It is much easier to manage group permissions, than to manage permissions on an individual-user basis.

Thank you!!

If you find this is worth to you Please mark helpful.

Prasant Kumar 1 · ‎08-23-2021

Helpful.