C.2 Creating a New Query using the JavaScript API

As an alternative to using the basic search request parameters, or the JSON structure, you can call a JavaScript API to execute queries. This section describes some simple techniques for using the API, as well as reference documentation for the API.

The search API relies on the ajax framework embedded in the identity applications component named JUICE. JUICE (JavaScript UI Controls and Extensions) is compliant with and uses the dojo library. JUICE is merged into the dojo release used in the identity applications.

Therefore, to use JUICE on a custom page within the IDM User Application WAR file, you need to have a script reference to dojo.js (not to JUICE). After adding the reference to dojo.js, you can add a JavaScript line to tell dojo to download JUICE.

Before using the JavaScript API, you need to perform some setup steps on the page to make the dojo module available for use:

  1. Add a script tag for dojo.js in the HTML header. The reference to dojo.js must be in the header (not the body), as shown below.

    <html>
    <head>
    <META http-equiv="Content-Type" content="text/html; charset=UTF-8">
    <title>JavaScript Search</title>
    <script type="text/javascript">
      if(typeof dojo=="undefined"){
        var djConfig={isDebug: false, 
                      baseScriptUri: "/IDMProv/javascript/dojo/"};
        var buf="<script type='text\/javascript' ";
        buf+="src='/IDMProv/UIQuery?js=dojo\/dojo.js'><\/script>";
        document.writeln(buf);
      }
    </script>
    </head>
  2. Add this JavaScript statement to load JUICE into the browser’s memory:

    <script type="text/javascript">
      //This line must precede any code using JUICE.
      dojo.require("JUICE.*");
    </script>
  3. To take advantage of the JUICE.IDM services, which include entity searching, also add this JavaScript statement:

    <script type="text/javascript">
      //This line must precede any code using JUICE.IDM services.
      dojo.require("JUICE.IDM.*");
    </script>

To build the query, you need to call the create() method on the JUICE.IDM.Entities.Search object, passing in the name you want to give to the query. The create() method is a static method. Here’s how you invoke it:

var newQuery = JUICE.IDM.Entities.Search.create("My New Search");

Once you’ve created the query object, you can call methods on this object to define the basic settings for the query, as well as the condition groups and condition rows. The query structure you create with the JavaScript API follows the model of the JSON representation. After you’ve created the query object you append it to the QUERY request parameter.

The JavaScript example shown below illustrates how you use the JavaScript API to build a query:

function buildQuery3() {
  var newQuery = JUICE.IDM.Entities.Search.create("My New Search");
  newQuery.setFrom("user");
  var selAttrs = ["FirstName","LastName"];
  newQuery.setSelects(selAttrs);
  var newCondGrp1 = newQuery.addConditionGroup();
  var newCondRow1_1 = newCondGrp1.addConditionRow();
  newCondRow1_1.setRowAttr("FirstName");
  newCondRow1_1.setRowRop("contains");
  newCondRow1_1.setRowVal("C");
  openSearchResults("QUERY=" + newQuery);
}

C.2.1 JavaScript API

This section provides reference documentation for the JavaScript API for searching entities in the Directory Abstraction Layer.

The following table describes the static methods for the JUICE.IDM.Entities.Search object:

Table C-5 Static methods for JUICE.IDM.Entities.Search

Method

Description

<Query> (createsearchName)

Creates a new Query with the searchName

<void> load(uuid)

Loads a user's saved search with the uuid

<Query> get(uuid)

Returns the user's saved search with uuid as a Query

<String[]> getNames()

Returns the names of all the logged in user's saved searches

<String> getUUID(searchName)

Returns the uuid of the saved search with the searchName

The following table describes the methods for the Query object:

Table C-6 Methods for the Query object

Method

Description

<void> setKey(searchName)

Sets the searchName

<void> setFrom(defKey)

Sets the from entity-definition

<void> setSelects(attrKey[])

Sets the selects (optional, if using SearchListPortlet)

<void> setSearchScope(scp)

Sets the search scope (optional)

<void> setSearchRoot(rt)

Sets the search root (optional)

<void> setMaxPage(int)

Sets the max rows per page (optional)

<void> setMaxResults(int)

Sets the max rows in total (optional)

<void> setOrderBy(attrKey)

Sets the sort (optional)

<void> setPointer(int)

Sets the pagination offset (optional)

<void> setGroupLop(lop)

Sets the inter-group logical operator

<String> getKey()

Gets the searchName

<String> getFrom()

Gets the from entity-definition

<String> getSelects()

Gets the selects

<String> getSearchScope()

Gets the search scope

<String> getSearchRoot()

Gets the search root

<int> getMaxPage()

Gets the max rows per page

<int> getMaxResults()

Gets the max rows in total

<String> getOrderBy()

Gets the sort

<int> getPointer()

Gets the pagination offset

<String> getGroupLop()

Gets the inter-group logical operator

<int> nbConditionGroups

Returns the number of condition groups

<CondGroup> addConditionGroup

Creates and returns a new condition group (CondGroup object) appended to the query

<void> removeConditonGroup(i)

Removes the condition group at i

<CondGroup> getConditonGroup(i)

Returns the condition group at i

The following table describes the methods for the CondGroup object:

Table C-7 Methods for the CondGroup object

Method

Description

<void> setRowLop(lop)

Sets the intra-group logical operator

<String> getRowLop()

Gets the intra-group logical operator

<int> nbConditionRows()

Returns the number of condition rows

<CondRow> addConditionRow()

Creates and returns a new condition row appended to the condition group

<void> removeConditionRow(i)

Removes the condition row at i

<CondRow> getConditionRow(i)

Returns the condition row at i

The following table describes the methods for the CondRow object:

Table C-8 Methods for the CondRow object

Method

Description

<void> setRowAttr(attrKey)

Sets the attribute

<void> setRowRop(rop)

Sets the relational operator.

<void> setRowVal(val)

Sets the search value

<String> getRowAttr()

Gets the attribute

<String> getRowRop()

Gets the relational operator

<String> getRowVal()

Gets the search value