About the LDAP Query Options Editor

Use this tab to specify the query to perform. The values that you specify for each property of the query determine which directory items (or object types) are returned by the query.

Base-DN

The item at the top level of the LDAP directory tree that includes the directory branches that you want to make available to your queries. Specifying a base DN can increase the efficiency of queries when the LDAP directory has many top-level objects.

Select the base DN from the list. The list contains all of the nodes at the top level. Click Refresh to ensure that the list is populated with current information from the LDAP server.

Search Context

A string value that represents the starting point for searches in the LDAP directory tree. The search is conducted in the branches of the LDAP directory tree that are contained in the directory item that you specify.

You can type the DN of the starting point or use an XPath expression if the value is saved as process data. The XPath expression must be enclosed within braces and dollar signs:

   {$expression$}

Search Filter

A string value that represents the search criteria for the query. The query returns information from the directory items that contain attribute values that match those described in the search filter. (See Search filter syntax.)

To specify a search filter, use the Search Query Builder dialog box (see About the Search Query Builder) and click the ellipsis button to display the dialog box.

Search Scope

A string value that represents the number of levels of information to search relative to the search context. The following values are valid:

OBJECT: Only the directory item specified for the Search Context property is searched. This is the smallest scope.

ONE LEVEL: The level below the search context searched, as well as the directory item specified for the Search Context property.

SUBTREE: All levels below the search context are searched, as well as the directory item specified for the Search Context property. This is the largest scope.

You should use the smallest scope that is necessary for the purposes of your query. The scope determines the number of directory items that are compared to the search filter. More server resources are used and more time is required to compare larger numbers of records.

Nested Context (LDAP Query To XML)

A string value that represents the attribute that contains the DN of another directory item. This directory item is retrieved in the query results instead of the items found based on the query's search context.

For example, the search context matches directory entries that represent employees. The value of the manager attribute of the returned entries is the DN of another directory entry, which represents the employee's manager. Specifying manager for the value of the Nested Context property returns the directory entry for the employee's manager.

The directory entry for the manager also includes the manager attribute. Specifying manager/manager for the value of the Nested Context property returns the directory entry for the manager's manager.

Use this tab to specify the information that you want to save from the search results. You save the information from specific attributes of the directory items. The values are saved in locations in the process data model.

If Multiple Objects Are Returned

Specifies whether you want to save information from only the first directory item that is returned by the query, or whether you want to save information from all of the returned items. If you want to save information from all items, you also specify the format of the retrieved data:

Use First: Saves information only from the first item that is returned. The data type is determined by the data you are retrieving.

Concatenated As String: For each directory item that is returned, the value of an attribute for each item is concatenated into a single string value. The character used to delimit each attribute value is specified in the Object Delimiter property on the Output Settings tab.

List: For each item that is returned, the attribute value of each record is stored as a string value in a list value.

Save Result Count Into

The location to save the number of items that matched the search filter. The data type is integer. If you save information from only the first returned directory item, this value enables you to determine if there are additional matching items found. It also enables you to determine if there are no items found.

Storage locations

The attributes of the returned directory items that you want to save, and locations in which to save the values. Click the + button to add a row to the table. After the row is added, you can populate the row with values:

Value: The name of the attribute that you want to save. Each cell in the Value column is a menu from which you can select an attribute name.

XPath: The location to store the attribute value. The data type is determined by the value that you specified for the If Multiple Objects Are Returned property. Each cell in the XPath column provides an ellipsis button that opens XPath Builder which you can use to provide an XPath expression for the data location.

Use this tab to specify the names of XML elements to use for storing retrieved attribute values. The XML document has the following structure:

<Root_Element>

   <Repeated_Element>

      <element1>attribute value</element1>

      <element2>attribute value</element2>

      <element3>attribute value</element3>

      .

      .

      .

   </Repeated_Element>

<Repeated_Element>

      <element1>attribute value</element1>

      <element2>attribute value</element2>

      <element3>attribute value</element3>

      .

      .

      .

   </Repeated_Element>

   .

   .

   .

</Root_Element>

Root Element

A string value that represents the name of the root element of the XML document.

Repeated Element

A string value that represents the name of the XML element to use to contain the information from a directory item. One of these elements exists for each directory item that the search returns.

Attribute/Element list

A list of directory item attributes and the names of the corresponding XML elements to use to store the attribute values. Click the + button to add a row to the table. After the row is added, you can populate the row with values:

Attribute: The name of the attribute for the found directory item or items that you want to save. Each cell in the Attribute column is a menu from which you can select an attribute name.

Element: The name of the XML element to use to contain the attribute value. Each cell in the Element column provides an ellipsis button that opens XPath Builder which you can use if the element names are saved in the process data model. If no value is specified, the name of the attribute is used as the element name.

This tab enables you to specify options for formatting the data that is retrieved from the LDAP directory.

Nested Context

A string value that represents the attribute that contains the DN of another directory item. This directory item is retrieved in the query results, in addition to the items found based on the query's search context.

For example, the search context matches directory entries that represent employees. The value of the manager attribute of the retrieved entries is the DN of another directory entry, which represents the employee's manager. Specifying manager for the value of the Nested Context property retrieves the directory entry for the employee's manager.

The directory entry for the manager also includes the manager attribute. Specifying manager/manager for the value of the Nested Context property retrieves the directory entry for the manager's manager.

Attribute Delimiter

A string value that represents the delimiter to use for values within attribute values. When attribute values are comprised of multiple values, these values are separated by the attribute delimiter.

Attribute Escape Delimiter

A string value that represents the character to use to escape the delimiters that are used in attribute values, when the values are comprised of multiple values.

Object Delimiter

A string value that represents the delimiter for objects that are returned when Concatenated as String is selected for the If Multiple Objects Are Returned property.

For example, a query returns two objects, John and Mary. John was a member of the groups groupA and groupB. Mary is a member of the three groups groupX, groupY, and groupZ. The object delimiter is ; and the attribute delimiter is $$. The attributes contain the following strings:

   name: John$$Mary

   memberOf: groupA;groupB$$groupX;groupY;groupZ

Object Escape Delimiter

A string value that represents the character to use to escape characters in object names that happen to be the same as the delimiters that are used to separate objects.

This tab enables you to test the query. Click Test to see the results of the query.

Note:   To perform the test, all property values must be specified as literals because XPath expressions can not be evaluated at design time.

The test only shows the data that is retrieved from the LDAP server, and does not show how the results are saved.