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 fieldwith "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 Tablewith "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..

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