SFDC Stop - Always the latest about Salesforce


Full Tutorial Series with videos, free apps, live sessions, salesforce consulting and much more.


Telegram logo   Join our Telegram Channel

Wednesday, 27 June 2018

Build Admin Friendly Custom User Interfaces Using Salesforce UI API

Salesforce User Interface API


I gave a live demo of Salesforce UI API at TDX18GG organized by New Delhi Salesforce Developer Group and Salesforce Gurgaon WIT User Group and in this blog post, I am going to give you all the resources of my session as well as a brief idea about Salesforce UI API and how you can implement it.

Let's have a look at the presentation first:-


Introduction to User Interface API

We already have a lot of APIs in Salesforce like:- Metadata API, Chatter Rest API, Tooling API etc. So the question arises that - Why Salesforce created UI API ?
To build Lightning Experience, the developers at Salesforce needed a new API because the existing APIs were designed for data integration not for building user interfaces. So, after discussions among themselves, UI API was born.

How UI API is different ?

UI API is developed specifically for building UI. Therefore, unlike other APIs which primarily focus on one particular thing, UI API gives you everything you need to build UI in one single package. It consists of the layout configuration, record data as well as metadata together to build custom and dynamic UI.

When you develop a custom UI, if you need to do any changes in the UI, you have to jump into the code to do that. Suppose, you need to swap two fields in the User Interface or remove a field, you need to go to the code and do the required changes right ? but with UI API, it's just a matter of few clicks..!!

As developers building Salesforce themselves used UI API to build lightning experience and they made their API public, so if you use UI API to create layout for your custom web or mobile application linked to Salesforce, it'll be synchronized with your UI at org automatically. This means that:-

If you do any changes in the layout in your Salesforce Org, the same changes will reflect in your custom UI automatically and it'll render automatically with the updated layout.

This is a very good and awesome feature of UI API, not only this, your sharing rules, field level security will be automatically handled by UI API itself i.e.

If a particular field is not visible in Salesforce to the user, it'll not be visible to the same user in your custom application using UI API.

Isn't that Amazing..?? But wait not only this, UI API provides you a lot more features listed below:-
  1. With UI API, you get the record information along with the layout information. That means you don't need to do any query to fetch the records separately in your UI.
  2. It provides you the data and metadata about the actions provided in the UI like custom buttons, quick actions etc. So that the custom buttons behave in the same way in your custom app to as they work in your salesforce org.
  3. You can easily perform CRUD operations on records with UI API.
  4. UI API makes it easier to implement dependent picklists in your custom UI by providing keys to match the records dependent on other records.

Live Demo - Salesforce UI API

I have given a live demo of UI API at global gathering but don't worry if you were not able to attend that. I am going to give you a brief demo about UI API now and provide you the whole code that I used in the demo. So, let's learn UI API step by step:-

To get started go to the workbench REST Explorer:- https://workbench.developerforce.com, choose your environment and click on login with Salesforce. Once you are logged in, you can navigate to the rest api explorer of workbench by hovering over the utilities option in the menu bar and then clicking on REST Explorer as shown below:- 


Once you are in the REST Explorer, you'll see a URL like this:- /services/data/v43.0/ in the text field with an execute button. It is used to hit any Salesforce API. Now we are going to hit UI API from this and will understand the response. Now, let's suppose I want to make UI for any record detail page that I need to show in my custom application. For this, copy and paste the given text in your text field:- /services/data/v43.0/ui-api/record-ui/<record-id> and hit Execute. Here, <record-id> can be the id of any record like:- account, contact that exists in your salesforce org. For example when I replace this <record-id> with the id of an account in my org, the final URL is as follows:- /services/data/v43.0/ui-api/record-ui/0017F00000qSAEy with the account id, and when I click on execute the final result is as given below:- 

As you can see in the above picture we have the following items in response:-
  1. eTag
  2. layoutUserStates
  3. layouts
  4. objectInfos
  5. records

eTag

eTag is basically used for HTTP Caching. If we want to reduce network traffic and increase our app's response time, we can make use of this eTag. The eTag is known as the Entity tag and it consists of a hash of a representation of our response and if that representation changes, a new eTag will be generated automatically. This means that if there are any changes in the layout or records or anything that is coming in the response, a new eTag will be generated otherwise the previous eTag will be there. In order to use this feature we can send the previous eTag in header while making another request so that if the response is the same, an HTTP 304 Not Modified response will be generated instead of the actual response data. To add eTag to the header, write like this:- 
If-None-Match: "3f443b7df24d5ee553e5b901fdfbf0ae"
 where If-None-Match is the header key to check the previous eTag while forming the response and after : is the actual eTag enclosed in "" (inverted commas). If there is no change the response will be like shown below:-


As you can see above, an HTTP 304 response will be given if the response is not changed i.e. any data present in the response is not updated.

This was a main concept of using UI API, the other response values are dynamic according to the request made and the response bodies can be understood by referring to the UI API original salesforce documentation. In our case, we are fetching the record UI whose response is explained in the documentation here. It is pretty simple to understand other response values while fetching record ui apart from eTag:-

  1. layoutUserStates:- Map of layout IDs to the user state information. Show whether each section in the layout is collapsed or not. Each section has a unique id.
  2. layouts:- A map  of object API names to the layout information of each object. It consists of whole description of the layout along consisting of every single data like which sections are collapsible and which field is present in which row and in which section, the number of columns in each section etc.
  3. objectInfos:- A map of object API names to each object's metadata. It consists of whole object metadata including:- fields, depend fields, child relationships, record types etc.
  4. records:- A map of record ids to each record's data. In the record-ui we provide the record id at the end, so the whole data in each and every field of that record will be given in this part. Record data is provided along with the api name of each field so that we can easily synchronize the whole data with the fields available and show in our custom layout.
Sharing rules and field level security are implemented automatically by the UI API depending upon the user hitting the API. (Try to turn off visibility of any field and then check that whether that field is in the response or not)

Moving on to React

I have also made a react application for my demo of UI API. You can clone the same from the github repository here. It consists of a very basic code to fetch the record layout with different fields that will change there position if you change the layout. So open your Git Bash, move into a directory you want to work in and execute the following commands:-
  1. git clone https://github.com/rahulmalhotra/SalesforceUIApi.git
  2. cd SalesforceUIApi
  3. npm install
  4. npm start

P.S.:- I am using a windows system and maybe the commands should be same inside the git bash on mac too but I don't have the right idea. Let me know in comments if there is something different for mac and I'll update this.

So, your react app will run and open in your browser at localhost:3000 port and you'll see something like below:-


Wow..!! Your react app is up and running. If you open the console, you'll see an error saying failed to fetch as the app was not able to connect to your salesforce org and fetch the account layout. To make it simple and to the point, I haven't used any oAuth or anything for authentication, If you move in to the src folder and then to the App.js, you'll see something like given below:-

So, as you can see in the above code snippet, in this.state I have hard-coded the access token and the account Id as I am fetching the account record, for the access token, you need to create a connected app in Salesforce and hit it by postman or any other tool and account Id is simply the id of any account in your org. Then you can see that in the render() I have simply given a heading - Salesforce UI API Demo with React and called ViewAccount component by passing the accountId and accessToken in that as parameters.

Note:- If you don't know how to create a connected app or get the access token via postman let me know in comments and I'll create a separate post for that too.

Now if you see ViewAccount component in the src folder, in the constructor, I have called fetchAccountDataFromUiApi() this method is hitting my salesforce URL by using fetch() and setting up the required info to send like the account Id is concatenated at the end of the URL, request type is GET and headers consists of 'Bearer ' along with the access token concatenated with that, you can change the domain to your own salesforce org domain. In the response, I have extracted the sections and fields from the api where sections are from layouts and fields are from records key of the UI API as we need both. In the render() again I have simply written This is a simple component to view account and then called the layoutSections() which is passing the sections and fields information to LayoutSections component.

In the LayoutSections component, it is extracting the rows from sections and passing the rows and fields to LayoutRows component.Similarly, in the LayoutRows component, it is extracting the fields in each row and mapping it's value by checking the api name with the fields data we have and displaying it in a div.

If you have set the access token, record Id and URL correctly, the final output will be as follows:-


So, as you can see, the Account Information is the section name is there and if I see my account layout in the org, it is as follows:-


As, you can see that in both the layouts, my rows contain data as follows:-

Account Owner -> Phone -> Account Name -> Rating and so on....

Now it's time for magic. Let's edit our account layout in the org so that it's like given below:- 



You can see now, that the rows contain data as follows:-

Rating -> Account Name -> Phone -> Account Owner and so on....

Now if I refresh my react application, I'll see something like this:- 


Now, as you can see that the fields are in the same order in my custom layout also when I changed the order in my Salesforce Org. This is the beauty of UI API. Although my layout is not much appealing and I am sorry for the same :P But, it works for demo right..!!

So, that's all for this post. Let me know if you have any queries or suggestions in comments section below.

Sharing a picture of my session below, hope to see you in the next one too.


Happy Trailblazing..!!

8 comments:

  1. This comment has been removed by a blog administrator.

    ReplyDelete
    Replies
    1. Please don't spam. I am going to delete this right now

      Delete
  2. Thank you once again for this wonderful tutorial. Sure a demo on how to create a connected app or get the access token via postman will be very helpful.

    ReplyDelete
    Replies
    1. Bookmarked your suggestion Alo. Will write a post on the same for sure :-) Do share this post in your network too.

      Delete
  3. Hi. Can you help me please. How can we get access token or how we can login via application? I tryied to send a request to login but I got an CORS error.

    ReplyDelete
    Replies
    1. Hi Viktorria, usually a CORS error is managed on server side, while calling out we can set a header parameter to allow cors but that doesn't work all the time. So, it depends which is your client and server in case of a request being made.

      Delete
  4. Hi. Can you help me please? How can we get access token or how can we login via react application. I tryied to send a login request, but I had a CORS error.

    ReplyDelete