UI Builder - GraphQL Data Brokers

[Chris Pearson]

Disclaimer: The ideas, thoughts, and opinions in this post reflect my own views and do not necessarily represent the views of my employer, Accenture. 

Graph what now? 

You didn't think you'd be able to start using UI Builder without learning ANYTHING new did you? 

"GraphQL is a query language for your API, and a server-side runtime for executing queries by using a type system you define for your data." - From the website https://graphql.org/learn 

I highly recommend jumping to the above website and checking out their resources on GraphQL. ServiceNow UI Builder incorporates GraphQL queries to retrieve information from the DB in order to serve it up to the client and display it (bind the returned data) to specific components on a page. 

Why not just use plain old GlideRecord server side code to query tables and return data? The benefit of using GraphQL is that you can instruct the query to only return back specific attributes of the record(s) you query for, which improves performance that becomes critical at scale for large customers with numerous users hitting their workspace and portal experiences all at once. 

On a GraphQL Data Broker record, the critical fields are 'Properties' and 'Query'. The Properties field defines any variable properties that the user of this data broker can configure inside of UIB. The format of this field is an array of JSON objects. You can create a new GraphQL Data Broker by navigating to the 'GraphQL Queries' module in the left hand nav. 

Example: 

[{ 
  "name": "filter", 
  "label": "Simple Task filter", 
  "description": "Query conditions in the 'encoded query' format, for filtering the Simple Task data", 
  "readOnly": false, 
  "fieldType": "condition_string", 
  "mandatory": false, 
  "defaultValue": "", 
  "typeMetadata": {"table": "x_81275_simple_tas_simple_task"} 
}] 

The Query field defines your GraphQL query. Here is an example where we query a custom table called Simple Task and use a query from our properties that's in the format of an encoded query. The results we want back are also defined here along with whether or not we want the value or display value for each field on the returned object. 

query($filter: String) {   
GlideRecord_Query {x_81275_simple_tas_simple_task(queryConditions: $filter) { 
_results { 
        sys_id { 
          value 
        } 
        number { 
          value 
        } 
        requester { 
          value 
          displayValue 
        } 
          priority { 
          displayValue 
        } 
      } 
    } 
  } 
} 

Switching over to UI Builder, we can see immediately if we have formed our query properly by adding the GraphQL Data Broker to our page and setting the broker properties. We can see in our Output panel, the data being returned is good and it is only delivering the attributes of the data we defined in our GraphQL query. Note that the requester attribute (which is a reference field on the table) is giving us the value (sys_id) and the display value of the field just like we asked it to. 

This was a big bite of the cookie. It'd be good to chew on that for a while. Review the resources available on the website linked to above and of course check out the Docs and Developer sites for more details and examples.