UI Builder - Transform 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. 

In my last post, I highlighted the power of using GraphQL data brokers to retrieve just the necessary amount of data from the DB. Now I'll show how we take that data and get it into a format that we can more easily use in UIB. 

Although GraphQL data brokers form a 'data' object returned from the DB, we may need to work with that data by modifying it or adding to it prior to binding it to a component in UIB. We can do this by running the output of the GraphQL data broker through a Transform Data Broker. As we run this output through a Transform Data Broker we can use the power of server-side code to massage or add to this data as we see fit in order to produce the necessary data our Experience page calls for. 

We start by creating a new Transform Data Broker ('Transforms' module under the Data Management section of the Now Experience Framework app). 

We set the Properties field to a JSON object which allows us to select the output of our GraphQL data broker as its value. 

[{ 
  "name": "simpleTaskQueryData", 
  "label": "Simple Task Records", 
  "description": "Simple Task records from GraphQL query", 
  "readOnly": false, 
  "fieldType": "object", 
  "mandatory": false, 
  "defaultValue": "" 
}] 

Next, we write a Javascript function which takes as its only parameter, the input from our single property above. This function then can iterate through the output of our GraphQL broker and massage it as necessary before creating a new object to return back to UI Builder. 

In this example, we're taking data from our GraphQL broker and adding additional text to make the output more conversational. 

function transform(input) { 
   var returnObj = {}; 
   var returnArray = []; 
   //Get our object from the GraphQL data broker results 
   var records = input.simpleTaskQueryData.data.GlideRecord_Query.x_81275_simple_tas_simple_task._results; 
   //Cycle through the results object and transform the data as needed, forming our new object as our output 
   for (var i = 0; i < records.length; i++) { 
      var simpleTaskObj = {}; 
      simpleTaskObj.sysId = records[i].sys_id.value; 
      simpleTaskObj.number = 'Ticket number: ' + records[i].number.value; 
      simpleTaskObj.requester = 'For user: ' + records[i].requester.displayValue; 
      simpleTaskObj.priority = 'With a Priority of: ' + records[i].priority.displayValue; 
      simpleTaskObj.state = 'The current State of the request is: ' +  records[i].state.displayValue; 
      returnArray.push(simpleTaskObj); 
   } 
   returnObj.data = returnArray; 
   return returnObj; 
} 

Note: Anytime you create a new Data Broker, make sure you add a Read ACL for each Data Broker used in your Experiences with proper roles/conditions. 

The above example takes the output from our original GraphQL broker, which looks like this: 

{ 
  "data": { 
    "GlideRecord_Query": { 
      "x_81275_simple_tas_simple_task": { 
        "_results": [ 
          { 
            "sys_id": { 
              "value": "abd1dfa52f222010bd7b3f96f699b66e" 
            }, 
            "number": { 
              "value": "SIM0001001" 
            }, 
            "requester": { 
              "value": "681ccaf9c0a8016400b98a06818d57c7", 
              "displayValue": "Joe Employee" 
            }, 
            "priority": { 
              "displayValue": "Low" 
            }, 
            "state": { 
              "displayValue": "New" 
            } 
          } 
        ] 
      } 
    } 
  } 
} 

And transforms it into an object which looks like this that meets our requirements: 

{ 
  "data": [ 
    { 
      "sysId": "abd1dfa52f222010bd7b3f96f699b66e", 
      "number": "Ticket number: SIM0001001", 
      "requester": "For user: Joe Employee", 
      "priority": "With a Priority of: Low", 
      "state": "The current State of the request is: New" 
    } 
  ] 
} 

Now we can access the much simpler and 'massaged' output from our Transform Data Broker in our UIB components!