Start tracking your progress
Trailhead Home
Trailhead Home

Build UI to Edit a Record

Learning Objectives

After completing this unit, you’ll be able to:
  • Make a request to User Interface API to update a record.
  • Describe what’s special about compound fields.
  • Make a request to User Interface API to update a compound field.

Use Workbench to Call User Interface API

We’re going to use Workbench to make an API call to update the Universal Containers record.

Workbench is a suite of tools for interacting with your Salesforce org through the API. Because you can make REST requests from any HTTP sender, there are plenty of other tools available for you to use (for example, check out cURL or Postman). But because Workbench provides a friendly framework specifically for Salesforce APIs, it’s the perfect way to dig in before you’re ready to write a full-on integration.

The first step is to log in to Workbench.
  1. Log in to your Trailhead Playground. In another browser tab, navigate to Workbench.
  2. For Environment, select Production.
  3. For API Version, select the highest available number.
  4. Make sure that you select I agree to the terms of service.
  5. Click Login with Salesforce.

You’ve arrived at the Workbench home page. For this module, we use only one of Workbench’s many tools, the REST Explorer.

In the top menu, select utilities | REST Explorer.

You can make User Interface API calls from the REST explorer just like you would from any other HTTP interface.

Workbench call to /ui-api/object-info resource.

To make an API call, enter the resource URI, select an HTTP method, add a request body as needed, and click Execute.

Go ahead and use Workbench to make that request now! Enter this URI, select GET, and click Execute.
/services/data/v45.0/ui-api/object-info

The response is a list of all the objects that User Interface API and your Trailhead Playground support.

Note

Note

If you get an error, make sure your URI includes v45.0, which is the API version.

Edit a Record

In the Record Viewer app, when a user clicks to create a record, the request to /ui-api/record-ui/{recordIds} asks for both view and edit modes. The JSON response includes layouts for each mode, so the app has enough information to build a form that lets users edit the record when they decide to.

let recordViewUrl = action.creds.instanceUrl + '/services/data/v45.0/ui-api/record-ui/' 
  + action.recordId + '?formFactor=' + action.context.formFactor + '&layoutTypes=Full&modes=View,Edit';

To let a user edit a record, the app displays a form with editable fields. When a user clicks Save, the recordUpdater.js saga makes a PATCH request to the /ui-api/records/{recordId} resource to perform the update.

let recordDataUrl = action.creds.instanceUrl + '/services/data/v45.0/ui-api/records/' + action.recordId;

Let’s use Workbench to update a record and then view the change in the Record Viewer app and in Salesforce. First we need the ID of the record to update.

In the Record Viewer app, in Recent Items, click Universal Containers. Copy the record ID to use in the PATCH request. You can copy the ID from the field at the top of the app, or you can click Show JSON and click records to see the record ID. Here’s some sample JSON that looks similar to what you see.
"records": {
    "0010V00002JoU6hQAF": {
      "apiName": "Account",
      "childRelationships": {},
      "eTag": "412642214dd7ef34eb3e2bae5e645dcc",
  1. In Workbench, click Utilities | REST Explorer.
  2. Enter these settings:
    • HTTP method: PATCH
    • Resource URI: /services/data/v45.0/ui-api/records/{recordId}

      Replace {recordId} with the Universal Containers record ID.

    • Request Body:
      {
          "fields" : {
              "Website": "www.example.com",
              "Rating" : "Hot"
          }
      }
  3. Click Execute.
  4. Return to the Record Viewer app and click View Record to reload the Universal Containers record.

    The Website and Rating fields have been updated. You can also view the change in your Salesforce org.

Edit a Compound Field

Compound fields can be a bit trickier to update. A compound field groups multiple fields with primitive data types, such as numbers or strings, to represent a complex data type, such as a location or an address. A compound field is made up of component fields.

For example, BillingAddress is a compound field. Its component fields are BillingStreet, BillingCity, BillingState, and BillingCountry. The values in the compound field and the values in the component fields both map to the same underlying data stored in Salesforce; they always have identical values.

Compound fields are read-only. To edit to a compound field, you have to update its component fields.

If a field is a compound field, its objectInfo.fields[fieldName].compound property is true.
"BillingAddress" : {
  "apiName" : "BillingAddress",
  "calculated" : false,
  "compound" : true,
  "compoundComponentName" : null,
  "compoundFieldName" : null,
  ...
If a field is a component of a compound field, its objectInfo.fields[fieldName].compoundComponentName property contains its component name and its objectInfo.fields[fieldName].compoundFieldName property contains the name of its compound field.
"BillingCity": {
  "apiName": "BillingCity",
  "calculated": false,
  "compound": false,
  "compoundComponentName": "City",
  "compoundFieldName": "BillingAddress",
  ...
To update an address, provide the component fields as separate inputs. For example, BillingAddress is a compound field so it’s read-only. To update it, you have to update its parts.
  1. In Workbench, click Utilities | REST Explorer.
  2. Enter these settings:
    • HTTP method: PATCH
    • Resource URI: /services/data/v45.0/ui-api/records/{recordId}

      Replace {recordId} with the Universal Containers record ID.

    • Request Body:
      {
        "fields" : {
          "BillingPostalCode": "98112",
            "BillingState": "WA",
            "BillingCity": "Seattle",
            "BillingStreet" : "123 Main Street",
            "BillingCountry" : "USA"
        }
      }
  3. Click Execute.
  4. Return to the Record Viewer app and click View Record to reload the Universal Containers record.

Look at the updated record in the Record Viewer app.

In view mode, it’s nice to render a compound field as a single field. Compound field in view mode.

In edit mode, render the component fields so a user can change them. To see the record in edit mode, click Edit.Component field in edit mode shows each component field.

ETags

ETag is an HTTP header that uniquely identifies a response. Your app can pass an ETag back to Salesforce using the If-None-Match HTTP request header.

If the JSON that Salesforce is going to send back is the same as what you have, you get an HTTP 304, which means that nothing has changed, and your app doesn’t have to deserialize another payload.

Using ETags cuts down on network traffic and data usage, and improves the performance of your app. It’s useful for object and layout metadata payloads, because they don’t change often.

Every response from User Interface API has an eTag property that contains an ETag HTTP header, which is an opaque identifier that corresponds to the resource. You can see the eTag property and identifier in a collapsed response from /ui-api/record-ui/{recordIds}.
root:{} 5 items
eTag:19d49d8dfba088456235a7cacc38138a
layoutUserStates:{} 1 item
layouts:{} 1 item
objectInfos:{} 1 item
records:{} 1 item

If we expand layouts, objectInfos, and records in the JSON response, we see that each of those nested responses also contains an eTag property. That’s because UI API has resources that return each of those nested responses as top-level responses. In an aggregate payload like /ui-api/record-ui/{recordIds}, each chunk of the payload has an ETag.

These resources return the nested responses as top-level responses.
  • /ui-api/layout/{objectApiName}
  • /ui-api/object-info/{objectApiName}
  • /ui-api/records/{recordId}
retargeting