Candidate Queries

A candidate query is an LDAP Query assignment to a position or group.

Candidate queries are configured using the setGroupCandidateQuery and setPositionCandidateQuery functions. After a candidate query is configured, the query is scheduled to run, using the AutoResourceGenStart property in the DE.properties file, and candidates are assigned to the group or position. For information about all candidate query-related properties, see the TIBCO ActiveMatrix BPM Administration guide.

An LDAP container must be specified in the setGroupCandidateQuery and setPositionCandidateQuery functions. The primary LDAP source of the LDAP container identifies the LDAP connection on which the query is performed. This also determines the LDAP container to which any newly created resources are assigned.

Depending on the class of the primary LDAP source of the LDAP container, further configuration may be allowed. There are two classes of LDAP sources:

  • Those that identify candidates as the members of an LDAP group. For this class, no further configuration is available; the candidate query will take all the entries identified by the LDAP container as its candidate list.
  • Those that identify candidates using an LDAP query. For this class, the following additional configuration is available:
    • Base-DN - Names the LDAP branch to which the LDAP query (see below) will be restricted. This is optional and is relative to any Base-DN already configured on the primary LDAP source of the identified LDAP container.
    • LDAP Query - This expression locates entries that identify candidate resources. The expression is combined with that of the primary LDAP source of the identified LDAP container.
    • Search Scope - This determines the depth to which the search is performed, as follows:
      ONELEVEL Only the elements directly within the Base-DN level are searched.
      SUBTREE Elements directly within, and below, the Base-DN level are searched.

      The candidate query cannot be more inclusive in its Search Scope than the LDAP container's primary LDAP source. Therefore, if the primary LDAP source has a search scope of ONELEVEL, then the candidate query must also use ONELEVEL. However, if the primary source is SUBTREE, then the candidate query may be either.

The Base-DN and LDAP Query of the LDAP container’s primary LDAP source are combined with those of the candidate query. The following table shows how the properties are combined.

  Base-DN LDAP Query
Primary LDAP Source o=acme (objectclass=person)
Candidate Query ou=london (department=1234)
Combined Result ou=london,o=acme (&(objectclass=person)(department=1234))

Any resource identified by the candidate query of a group or position must also be visible via the associated LDAP container. That is, no resource can be created dynamically that could not also be created manually using an LDAP container. This ensures that any resource attributes are able to retrieve their values from the mapped LDAP attributes of an LDAP container.

Each candidate query will only identify potential entries from the primary LDAP source of the associated LDAP container. If that LDAP container has any secondary LDAP sources, the rules that bind entries within the secondary LDAP sources to those of the primary LDAP source must be followed. It is only when those rules have been completed that the true set of candidate resources can be resolved.

The deletion of the LDAP container will, depending on the request parameters, cause the deletion of all resources belonging to that LDAP container; whether they were created manually or dynamically. If the request to delete the LDAP container does not specify that associated resources should also be deleted, and associated resources exist, the request will fail. The deletion of the LDAP container will always result in the deletion of candidate queries that reference that LDAP container.

Populating Instantiated Model Templates Using Substitution Variables

Positions and groups can be populated using candidate queries assigned to those positions and groups. By extending this slightly, and assigning candidate queries to positions within an organization model template (see Configuring a Dynamic Organization Model Extension Point), it is possible to both instantiate an organization model template, and populate it.

By using simple variable substitution, it is possible to construct the Base-DN and/or the LDAP query of the candidate query in such a way that it identifies the resources for a particular organization model template instance. The substitution variables must be enclosed in braces: { }.

The following substitution variables are available for reference within a candidate query (the variable names are case-insensitive):

  • Root-DN - The DN of the LDAP entry that initiated the organization model template instance.
  • Root-Name - The name assigned to the root organization unit of the model template instance; that is, the value of the LDAP attribute named in the extension point.

An example of a Base-DN containing substitution variables: 

   "ou= {root-name} , {root-dn}"

An example of an LDAP Query: 

   "(&(ou= {root-name} )(dept=123)(role=manager))"

Candidate query substitution variables can only be used for organization model templates, and are evaluated only when the organization model template is instantiated.