Leveraging Zurich's Component Builder for EVAM View Templates

[Daxin]

Entity View Action Mapper (EVAM) is a powerhouse for showing dynamic data in ServiceNow's Next Experience. While the out-of-the-box (OOB) components like now-card-evam-record are useful, you'll inevitably face a scenario where you need a unique look and feel that OOB just can't provide.

This is where custom components come in.

The Old Way vs. The New Way (Thank You, Zurich! 🙏)

Before the Zurich release, creating a custom component was a heavy lift. It involved setting up a local development environment, using the command-line interface, and a lot of pro-code effort.

Thankfully, Zurich introduces the Component Builder, a game-changer that lets us build reusable components directly within UI Builder. This article will show you how to build a simple custom component and, more importantly, how to wire it into an EVAM View Template to display your data.

Step 1: Build a Simple Custom Component

First, let's create a basic component to display a label and a value.

1. Navigate to Now Experience Framework > UI Builder.
2. Click Create component and give it a name, like Simple Title Component.
3. Inside the component editor, add two Stylized Text components.
4. Name them logically in the Content panel. For example:
• Title Label
• Title Value

Step 2: Define Component Properties to Receive Data

To make our component dynamic, it needs a way to accept data from EVAM. We'll use component properties for this.

1. In the UI Builder editor, under the Properties and Policy section.
2. Click + Add to create two new properties of type String:
• titleLabel
• titleValue
3. Now, bind these properties to your Stylized Text components.
• Select the Title Label component. For its Text configuration, use a data binding and bind from the component property titleLabel
• Select the Title Value component. For its Text configuration, use the data binding and bind from the component property titleValue

Your component is now ready to receive and display data through its properties.

Step 3: Get Your Component's sys_id

This is a critical step! You need the actual sys_id of the component record, not the ID you see in the UI Builder URL.

1. While in the component editor, click the menu icon and select Open component record.
2. The sys_ux_macroponent record for your component will open in the classic platform view.
3. Copy the sys_id of this record. You'll need it for the EVAM View Template.

TIP: The macroponent sysid is available as the component property as well (nowMacroponentSysId)

Step 4: Configure the EVAM Definition

Now, let's set up the EVAM side to provide the data. For this guide, we'll create a simple EVAM definition to display active incidents.

(If you're new to EVAM, check out the excellent EVAM guide on the ServiceNow Developer Blog first.)

1. EVAM Definition: Create a new EVAM Definition (e.g., "Demo EVAM Def").
2. EVAM Datasource: Create a datasource that queries the incident table for records where active=true. Link it to your definition
3. EVAM View Config Bundle: Create a bundle to hold our view configurations. Link it to your definition.
4. EVAM View Config: Create a new View Config. In the Fields section, add the fields you want to display, such as short_description and number. This makes the data available for mapping.

Step 5: Create the EVAM View Template

This is where we connect our data to our custom component. The View Template is a JSON object that tells EVAM which component to use and how to map the data fields to the component's properties.

1. In your EVAM View Config, locate the View Template reference field and create a new record.
2. Populate the Template field with the following JSON structure:

JSON

{

  "component": "macroponent-1234abcd1234abcd1234abcd",

  "mappings": {

    "titleLabel": "short_description",

    "titleValue": "number"

  }

}

Let's break this down:

• "component": This is where you put your component's sys_id, prefixed with macroponent-. Replace 1234abcd... with the sys_id you copied in Step 3.
• "mappings": This object connects the data to your component.
• The key ("titleLabel") is the name of your component property (@properties.titleLabel).
• The value ("short_description") is the name of the data field from your EVAM View Config.

Step 6: Put It All Together and Test It! 🚀

Let's see our custom component in action

1. Open or create a page in UI Builder.
2. In the page's Data panel, add a new EVAM Data Resource and select the "Demo Evam Def" definition we created earlier. We should be able to view the data, if there are no “items” then there could be some issue with the mapping/template.
3. Add a Data Set component to the page.
4. Configure the Data Set component to use the EVAM Data Resource as its data source.

Save and preview the page. You should now see a list of your active incidents, each one rendered using your custom component!

Next Steps: Handling Events

We've successfully linked a custom component to an EVAM template for display. But what about making it interactive? In a future post, I'll dive into handling events, so you can perform actions (like navigating to the record) when a user clicks on your custom component.