Skip to main content

IMPORTANT - Product End of Life Statement - IMPORTANT

Request RE, Survey, and Calendar 1.5 Support Ending December 31, 2020
Contact Kinetic Data Support with Questions
Kinetic Community

How to Test a Bridge with JavaScript

This tutorial explains how you can quickly test the validity of a bridge using the JavaScript console in Chrome.

Step 1: Expose Your Bridge Qualification in a Service Item

In a hidden or removed section, create a field that exposes your bridge qualification. In the example below, I had created a bridge to give access to the Incident Work Log form (HPD:WorkLog). The qualification I want to expose for use is named "by Incident Number".

Expose Your Bridges

Step 2: Open the Service Item in a Display Page

Open the Kinetic Request Service Item with the 'Open Anonymous' link. Be sure that the selected Display Page will load kd_client.js. This tutorial makes use of the recently added bridging code at the bottom of this JavaScript file. 

Step 3: Open Google Chrome JavaScript Console

Click on the Customize and Control button in the upper right-hand corner of Google Chrome. Select Tools --> JavaScript Console. You can also open and close it with Ctrl+Shift+J in Windows or Command+Option+J on the Mac.

Open Javascript Console.png

Step 4: Create a Bridge Connection Object

There are two constructors for a bridge connection object.  You can either use the empty constructor:

> var conn = new KD.bridges.BridgeConnector();

Or you can supply the ID of a template (i.e., the GUID of the service request) that has the exposed bridge qualification, along with the web application root (almost always "/kinetic/"):

> var conn = new KD.bridges.BridgeConnector({ templateId: "KS89b14d08601f15ed4f7167e1a3da85eba7", webAppRoot: "/kinetic/" });

Enter the code in the JavaScript console and press Enter. You should see the return value of "undefined" followed by a new prompt.  Now if you type the name of the object followed by a dot (.) you'll see a list of object properties and methods.

Object Methods and Attributes.png

For example, if you click on the templateId property, the value will appear after the dot.  Press Enter, and the console will display the property's value.

TemplateID Value.png

Step 5: Create Argument Variables

My qualification returns multiple values, so I will be using the search method. If it returned only one value, I would use the retrieve method. Either method takes the following arguments:

  • The name of the model (a string).
  • The name of the qualification (a string).
  • And a configuration object.

The first two arguments are fairly obvious. The third is anything but obvious.

The config object is a complex collection of:

  • parameters -- a hash of Qualification Parameters and their values.
  • attributes -- an array of Attributes whose values you want returned
  • metadata -- a collection of keys and values for doing things like sorting

For now, we'll just create parameters and attributes, because the metadata value is optional.

Create the parameters variable

For my bridge, I have a Qualification Name called "by Incident Number" where the query string looks like this:

'Incident Number' = "<%=parameter["Incident Number"]%>"

So I'm going to create a params object where the 'Incident Number' equals a certain value.

> var params = {'Incident Number' : 'INC000000000208'};

Create the attributes variable

Now I'll define the field values I want to get back from my Bridge query. I'll put some of the bridge attributes in an array.

> var attribs = ['Summary','Source','Work Info Type','Work Info Date'];

Use the argument variables in the search method

Finally, we can call the search method. This method supports a callback function definition, so on success you can perform some action with the return values.  I'm going to define a simple alert dialog that will show the data in JSON format.

>'IncidentWorkLog', 'by Incident Number', { parameters: params, attributes: attribs, success: function(response) { alert('Data->'+response.toJson()) } } );

Here's what it looks like in the browser.

Run the Search.png

Using the Metadata argument

Sometimes you will need to order your response dataset by a particular attribute. If you are returning any field value where the string field is over 255 characters, you will also need to set the metadata variable. The Change WorkLog provides a good example of the second situation.

First, we'll set the parameters

> var params = {'Change ID' : 'CRQ000000000001' };

Next, we'll set the attributes

> var attribs = ['Summary','Source','Work Info Type','Work Info Date'];

Finally, we'll run the search

>'ChangeWorkLog', 'by Change ID', { parameters: params, attributes: attribs, success: function(response) { alert('Hey!'+response.toJson()) } } );

But we immediately see that the code throws an error.

Run the Search 2.png

It turns out there is a longstanding bug in BMC's Change Work Log. The Summary (Description) field is unlimited, when it should only be 100 characters. The bridge thinks it needs to sort with the parameters given. Since we asked for the Summary field, it fails loudly.

Create the metadata for sorting

I want the list to sort by the Work Info Date field, so I need to use this notation:

<%= attribute["Work Info Date"]%>:ASC

However, the underlying JavaScript code needs to run a backend query, so that string needs to be encoded before we send it on. I also need to invoke the 'order' directive and then wrap it in a hash.  Here's what it looks like:

> var meta = {order: [encodeURIComponent('<%= attribute["Work Info Date"]%>:ASC')] };

Use the meta variable in our search method

>'ChangeWorkLog', 'by Change ID', { parameters: params, attributes: attribs, metadata: meta, success: function(response) { alert('Hey!'+response.toJson()) } } );

The JSON data now appears in the alert dialog:

Run the Search 3.png


This tutorial showed how to call the search method on the BridgeConnector class in the JavaScript console. You can use these quick shortcuts to verify that your bridge configurations are correct.