A data resource \[sys\_ux\_data\_broker\] in UI Builder mediates data between a component and the ServiceNow server. The data resource brings data from the server to the component, and it brings updated data back to the server based on interactions with the component.

## Why Data Resources?

In the early days of the Next Experience UI framework, all component handled their own data communication with the server (we call this type of component a **Connected Component**). Connected components were/are easy to set up but they lack the flexibility to be reused for different use cases and a side effect is that it’s difficult for us to optimize the data, caching, or network calls. Each instance of a connected component is a little black box that operates as a mini application. Any flexibility is controlled by the component author’s use of inputs and feature flags. This makes it more difficult for end users to consistently define the layout, composition, or interactions of these components, even if internally they are composed of reusable low-level components.

Because of that, we’ve been moving towards what we call **Presentational Components** that don’t handle their own data communication with the server. With these components, you bind data to the component’s properties and then the component uses events to communicate with other components or to send data back to the server.

But how do we get data from the server to feed into these presentational components? Well, that’s where Data Resources come into play. Data resources are defined using UXF metadata models and are dynamically generated at runtime which means that there is no hardcoded JavaScript and users are free to define any kind of server interactions they wish. These data resources can be defined by users, instantiated, and chained together to fetch rich and complex data sets that can be exposed to components.

Since we know what data is needed and how it's used, we can make optimizations in dealing with it. First, because the data is separated from the presentational components, multiple components can now hook into a shared state which means we can now de-dupe data that is shared and only fetch it once. Also, if the UI uses data from the tail end of a chained (composite) data resource, we fetch the entire chain as a single query. The endpoint processes the data we need and only returns the data we use in the UI. If data is used at various points through this chain, we return all the necessary data at each step. Our engineering teams are also continually looking at ways to optimize performance in UI Builder and data resources are a large part of that.

## Types of Data Resources

Now that we know why we need them, let’s explore the different types of data resources.

**GraphQL** lets you write and/or use a GraphQL query against a ServiceNow GraphQL API. If you’re building one of these you’ll need to specify the query body, but that’s about it.

**REST** lets you execute a REST request against a ServiceNow REST endpoint. You’ll need to specify an endpoint, query params, and a request body.

**Scriptlet** runs sandboxed, vanilla, client-side JavaScript. It is primarily used for transforming the output from one of the data resources above into something usable by your components. The scriptlet is more preferable than a transform because the scriptlet loads and runs faster due to not loading any external APIs.

**Transform** runs any ServiceNow server-side JavaScript. If you already have a library of script includes for your app you can use this type of data resource to consume that library.

**Composite** data resources are a combination of other data resources chained together. Using a composite instead of being the outputs of one DR to another allows us to optimize the performance. It’s especially useful for GraphQL+Scriptlet combinations.

**Controllers** are new in Tokyo and, when combined with preset-enabled components, can be automatically added to a page when the component is added. For now, this is only usable by ServiceNow’s internal engineering teams.

## Read vs Mutate

Each type of data resource can either read or mutate (write) data. This is controlled by a checkbox on the data resource record called **Mutates server data** which changes how UI Builder handles the data resource.

**Read** \[Mutates server data = false\]:

Runs when:

* The page loads
* Any client state parameters bound to its properties change
* The refresh event is triggered.

To pass data to its inputs you can bind data to its properties as shown below. In the example you can see that the _Table_ property is hardcoded to my recipe table, but the _Record_ property, which is expecting a record sys\_id, is bound to the _recipeId_ URL parameter. If that was a client state parameter and it changed it would cause the data resource to refresh.

**Mutate** \[Mutates server data = true\]:

Runs when:

* Its Execute event is triggered

To map data to its inputs you can pass data when the data resource is executed. You’ll see that, even though this data resource has properties, they’re not available when you add it to the page.

If we look at the Execute event handler you’ll see we can map its 4 properties there.

Because mutating data carries so much more risk than querying data it’s important to be very intentional about creating and using data resources. If your DR does write to the server it is very important that the checkbox is checked so it doesn’t try to run on page load, etc.

## Anatomy of a Data Resource

**Properties:** Each data resource can have its own set of unique properties, which are basically the inputs for the DR. You can find a list of types and the JSON schema here: [Component and Data Resource Properties in UI Builder](https://www.servicenow.com/community/next-experience-articles/component-and-data-resource-properties-in-ui-builder/ta-p/2331894)

**Script/Request body:** Based on the properties and whether you select _Script_ or _Query_ this is where you’ll specify what your data resource does with the properties provided. This can be a request body, GQL query, or script that queries or mutates data.

**Events:** Every data resource can fire a series of events**.** Each of them fire an event when they’re initiated, when they succeed, or if they fail.

For a data resource that queries data, these are called D_ata Fetch_ and show up on the Events tab in the Data panel in UIB.

For a data resource that mutates data, these are called _Operation_ and show up on the Events tab in the Data panel in UIB

These data resource events can be very helpful when developing in UIB. Many times you’ll want to run a script or show a message based on the results of a data fetch and attaching an event handler to the Succeeded event is a great way to do that. You may also want to introduce some error handling and messaging and using the Failed event is useful for those use cases.

## Common Data Resources

If you’ve opened the data panel in UI Builder you may have been overwhelmed with the number of data resources that show up. They are organized by Application they were created in, but most are in the Global tab. There are a few really common data resources that I generally use when developing in UI Builder:

1. Look up record – based on a sys\_id, look up a single record.
2. Look up records – based on the properties you specify, look up a set of records.
3. Create record – this mutate DR allows you to create a single record.
4. Update record – this mutate DR allows you to update a single record.

Honorable mention: Look up Properties/User/User Preferences

## Additional Information

If you’re looking for even more information on Data Resources in UI Builder, check out the following links:

Stay tuned for an upcoming Data Resources Best Practices article.