Skip to main content
Kinetic Community

Performing Bridge Searches in JavaScript Functions

Bridges can be used to populate Dynamic Lists, populate menus, set field dynamic defaults, or set-fields, but sometimes you want to populate a table or do something else that requires doing the bridge search via js. This article covers the details on the code necessary for doing a bridge search in a javascript function.

Resolution

First, you set up a connection.  Passing the templateId parameter into the BridgeConnector constructor is optional, and if it is not specified, this parameter defaults to clientManager.templateId.

var connector = new KD.bridges.BridgeConnector({templateId: clientManager.templateId});

Then you use either a retrieve, a search, or a count on that connection. The retrieve method can only be used with "Single" return type qualifications and returns a single Record object, and the search method can only be used with "Multiple" return type qualifications and returns a list of Record objects. The count method can be used only with "Multiple" return type qualifications and returns a RecordCount object.

/* When using Kinetic Request v5.2.8 or greater */
connector.search(bridgemodel, bridgequalification, {
      attributes: bridgeattributes,
      parameters: parameterdata,
      metadata: {"order": ['<%=attribute["Character Field 1"]%>:ASC', '<%=attribute["Create Date"]%>:DESC']},
      success: function(list) {
        //handle data
      }
    });
    
    
/* When using Kinetic Request v5.2.7 or below, manually encode attributes */
connector.search(bridgemodel, bridgequalification, {
      attributes: bridgeattributes,
      parameters: parameterdata,
      metadata: {"order": ['encodeURIComponent(<%=attribute["Character Field 1"]%>:ASC)', 'encodeURIComponent(<%=attribute["Create Date"]%>:DESC)']},
      success: function(list) {
        //handle data
      }
    });

Where bridgemodel is the name of the bridge model, and bridgequalification is the qualification name used for this query for the specified model.

 

Examples

Automatic URL encoding was added in Kinetic Request v5.2.8.  That means if you are using version 5.2.8 or greater, then you do not manually encode any values used in the attributes, parameters, or metadata properties.  This was illustrated in the search example above.

 

Search Example

connector.search('Data Management Console - Helper Data', 'Index 1 | Index 2 (exact match/null)', {

Retrieve Example

connector.retrieve('Data Management Console - Helper Data', 'By Record Id', {

Count Example

connector.count('Data Management Console - Helper Data', 'Index 1 | Index 2 (exact match/null)', {

The bridge attributes to be returned are then specified. Note these are the attributes specified in the bridge manager, not the names of the field on the original system. Note that attributes aren't necessary for a count, only for a retrieve or search.

Example

attributes: ["Character Field 1","Character Field 2","Character Field 3","Character Field 4",
          "Index Field 1","Index Field 2","Index Field 3",
          "Permission","Status"],

The parameters necessary for the specified qualification are the next item specified. Note that it can be important (depending on the source system of the data, to include " around the parameter data. For example, in Remedy, matches for text must be in " but $/NULL$ must not be. 

Example

parameters: {'Index Field 1':paramval1,'Index Field 2':paramval2},

Then, for a search, specifying the search (metadata) can be specified; this isn't necessary for a retrieve, since only one record is being returned, and it's not necessary for a count because attributes aren't being returned. This example is specifying the sort order, by request ID ascending. The format of this is slightly different from what might be expected. The attribute used for the sort needs to be specified as an attribute (inside <%=attribute["   "]%>). ASC is used to specify ascending, and DESC is used to specify descending. More than one attribute can be specified. The attributes are comma delimited in that case, and the attributes sorts are applied in the order they are specified.

Example

/* When using Kinetic Request v5.2.8 or greater */
metadata: {"order": ['<%=attribute["Request Id"]%>:ASC'] },

/* When using Kinetic Request v5.2.7 or below, manually encode attributes */
metadata: {"order": [encodeURIComponent('<%=attribute["Request Id"]%>:ASC')] },

Additional examples of possible metadata are pagesize and offset, which could be added to the above example as specified below. Any of these pieces of metadata can be specified with or without any of the others. The example just shows them all together to include how to do so.

Example

/* When using Kinetic Request v5.2.8 or greater */
metadata: {"order": ['<%=attribute["Request Id"]%>:ASC'], "pagesize": 2, "offset": 1 },

/* When using Kinetic Request v5.2.7 or below, manually encode attributes */
metadata: {"order": [encodeURIComponent('<%=attribute["Request Id"]%>:ASC')], "pagesize": 2, "offset": 1 },

Then you need to process your results. A search returns a KD.bridges.RecordList object with a records array, of KD.bridge.Record objects, within it. Each record has an attributes object within it containing the results for that record. In the example below, each attribute returned for each record returned are put into an array; then each of these records are pushed into an array. Then this array of arrays is used to populate a table with the returned data.

Search Example

success: function(list) {
        //iterate through each record returned
        for(var i=0;i<list.records.length;i++) {
        ​    //create an empty array
            var currrecord=[];
            ​
            ​//iterate through the attributes in the record
            for(var j in list.records[i].attributes) {
            ​  //if there is data in the attribute, push it into the current record array
              if (list.records[i].attributes.hasOwnProperty(j)){
                currrecord.push(list.records[i].attributes[j]);
              }
            }
            ​//push the populated record array into the data array
            dataArray.push(currrecord);
        }
        ​
        ​//use the returned information to populate a table
        populateTable(dataArray,tablecolumns);
      }
    });

The result for a retrieve is just one record object. It's more common to pull the desired attributes out individually in this case. The example below populates questions with the values returned.

Retrieve Example

success: function(record) {
                //place the existing values in the relevant fields
                KD.utils.Action.setQuestionValue("Data Type Name", record.attributes["Character Field 1"]);
                KD.utils.Action.setQuestionValue("Status", record.attributes["Status"]);
                KD.utils.Action.setQuestionValue("Category Level 1", record.attributes["Character Field 10"]);
                KD.utils.Action.setQuestionValue("Category Level 2", record.attributes["Character Field 11"]);
                KD.utils.Action.setQuestionValue("Category Level 3", record.attributes["Character Field 12"]);
                KD.utils.Action.setQuestionValue("Data Type Definition JSON", record.attributes["Character Field 13"]);
                KD.utils.Action.setQuestionValue("Data Type Access Permissions", record.attributes["Permission"]);

                KD.utils.Action.setQuestionValue("Bridge Model", dataModelJSON.bridgedata.bridgename);
                KD.utils.Action._fireChange(KD.utils.Util.getQuestionInput("Bridge Model"));
                
                //in this example the rest of workflow happens from within events attached to questions    
          }
        });

The result for a count is one KS.bridges.Count object, where the value is what you will want.

Count Example

success: function(count) {
        //display count   
        alert("There were "+count.value+" records returned");
        }
    });

The above are just examples of use based on an ARS Bridge connection to the KS_SRV_Helper form. Your bridge may send multiple parameters, the names of your attributes will be representative of what is defined in your bridge, and the sorting, if any, would be on whatever included bridge attributes are appropriate for your dataset.