UI Builder - Get and update data by Data Broker

Guido Bernuetz · ‎08-11-2022

I have spend a lot of time to find out the right settings to implement Data Broker. Here I have written down my experiences. Some of this may be helpful for others.

Types of Data Broker

UI Transforms (Data Broker Server Scripts)
- Editor Note: I always use this type
UI Scriptlets (Data Broker Scriptlets)
UI GraphQL Queries (GraphQL Data Brookers)

Prepare Input Properties for a Data Broker

To use a Data Broker on a page the control parameters (input properties) must be defined. This is a JSON Array of property definitions. The following attributes can be used to define a property.

Attribute Name	Description
name	The technical name (used in scripts)
label	Displayed label
description	Description, shown by click on the (i) icon
readOnly	Always “false”, Usage not clear, “true” make no sense for an input parameter
fieldType	Possible types: string, boolean, field, field_list, table_name, json, object, array, reference, number
valueType	The value type of the field type
mandatory	Mandatory input
typeMetadata	Additional Meta data Eg. to make a field or field list depended to previous selected table
defaultValue

The following types for input parameters are defined:

Field Type	Description
string	A single string
boolean	True/false
table_name	Selection of a table name
field	Selection of a single field, can be depended on a previous table_name field with "typeMetadata" the table input must be specified "typeMetadata": { "table": "@table", "variant": "ordered" }
field_list	Multiple selection of fields, can be depended on a previous table_name field
json	A JSON Object
object
array	An Array
reference	Reference to another Table with "typeMetadata" the reference must be specified "typeMetadata": { "reference": "customer_account" },
number	A numeric field with decimal separator

How to make a field list depended on the previous table name?

{
             "name": "displayfields",
             "label": "Display Fields",
             "description": "Display Fields",
             "readOnly": false,
             "fieldType": "field_list",
             "mandatory": false,
             "defaultValue": "",
             "typeMetadata": {
                    "table": "@table", // the previous input field
                    "variant": "ordered"
             }
       },

Example of 3 input properties:

[
    {
        "name": "table",
        "label": "Table Name",
        "description": "Table to query",
        "readOnly": false,
        "fieldType": "table_name",
        "mandatory": true,
        "defaultValue": ""
    },
    {
        "name": "displayfield",
        "label": "Display Field",
        "description": "Display Field",
        "readOnly": false,
        "fieldType": "field_list",
        "mandatory": false,
       "typeMetadata": {
            "table": "@table"
        },
        "defaultValue": "name"
    },
    {
        "name": "equery",
        "label": "Encoded Query",
        "description": "Encoded Query",
        "readOnly": false,
        "fieldType": "string",
        "mandatory": false,
        "defaultValue": ""
    }
]

UI Transforms (Data Broker Server Scripts)

This is a type where standard ServiceNow Server side script is used. I use this type for additional Data Broker Scripts

To access input parameter, access as property from “input”.

Parameter definition:

[
    {
        "name": "table",
        "label": "Table Name",
        "description": "Table to query",
        "readOnly": false,
        "fieldType": "table_name",
        "mandatory": true,
        "defaultValue": ""
    }
]

Script:

function transform(input) {
    var tableName = input.table;
}

Bind Data Broker results

Bind Data Query Broker

Data of Data Query Broker are bind to components by their name + suffix “output” + data element name
Example: @data.order_tree_data.output.items

Figure 1 - Used component and the binding

OR by an own output specification

Figure 2 - Output is defined as “idArray”

Figure 3 - Used component and the binding

Bind Data Mutating Data Broker

Results of mutating Data Broker are bind by the event “Operation Succeeded” to a client state parameter of type “String” by @payload.data.output.<elementName>.

The complete output can be bind to a client state parameter of type “JSON” by @payload.data.output

function transform(input) {
    var res = {
        cntClosed: 0,
        cntFailure: 0,
        status: "Tasks successful closed"
    };
…

    return res;
}

The Data Broker Event binding

Figure 4-Update a client state parameter with the result object

Figure 5 - display of result values in a modal dialog

Set access rights for a Data Broker

Every Data Broker need at least one ACL record!

How to:

Copy the sys_id of the data broker record
Create a new ACL record for ux_data_broker of operation “execute”
Click on blue triangle on name field to see normal input field
Put in the Name field the sys_id
Assign roles and/or condition and/or script

Thiago Pereira · ‎05-20-2024

Hi!

I did not find any documentation about this type of ACL and i have some doubts about how it works.

The application I am working contains strictly confidential information from our client and we would like to know more about how this type of ACL works as it needs the "snc_internal" role to work.

Is there any risk of data leakage?

best,

Thiago

Guido Bernuetz · ‎07-21-2024

the role assignment "snc_internal" is only an example. You can assign any kind of roles or conditions to define your own access right for this data broker.

ZeeshanKhan1 · ‎09-18-2024

Can you Check my Data Broker Server Script
Is it correct