Query-Objects
Description
Queries for objects based on attribute values.
Syntax
<ie:webject name="Query-Objects" type="OBJ">
<ie:param name="ATTRIBUTE" data="attributes"/>
<ie:param name="BASE" data="base_context_name"/>
<ie:param name="CONNECTION_ATTEMPT_INTERVAL" data="interval"/>
<ie:param name="CONNECTION_ATTEMPTS" data="attempts"/>
<ie:param name="DBUSER" data="dbuser_name"/>
<ie:param name="DEREF"
data="[SEARCHING | FINDING | ALWAYS | NEVER]"/>
<ie:param name="FILTER"
data="[character_string | "objectclass=*"]"/>
<ie:param name="GROUP_OUT" data="group_out"/>
<ie:param name="INSTANCE" data="application"/>
<ie:param name="PASSWD" data="dbpassword"/>
<ie:param name="SCOPE" data="[BASE | ONELEVEL | SUBTREE]"/>
<ie:param name="SIZELIMIT" data="number of entries"/>
<ie:param name="TIMELIMIT" data="number_of_seconds"/>
</ie:webject>
Parameters
|
Required
|
Optional
|
|
INSTANCE
|
ATTRIBUTE
|
|
BASE
|
|
CONNECTION_ATTEMPTS
|
|
CONNECTION_ATTEMPT_INTERVAL
|
|
DBUSER
|
|
DEREF
|
|
FILTER
|
|
GROUP_OUT
|
|
PASSWD
|
|
SCOPE
|
|
SIZELIMIT
|
|
TIMELIMIT
|
ATTRIBUTE
Specifies which attributes from the queried objects to return. An LDAP entry contains two types of attributes: user and operational.
◦ A user attribute is normally data that can be modified by an application that has sufficient privileges.
◦ An operational attribute is created and maintained by the directory and normally cannot be modified (such as creatorsName).
To view operational attributes, the specific attribute must be specified in the ATTRIBUTE parameter. If you specify "*", all user attributes are returned. Multiple parameters can be specified using the value "*" and the explicit operational attribute names to return. This combination returns all user attributes and the specified operational attributes.
If this parameter is not specified, all user attributes are returned. This parameter is optional.
BASE
Specifies the base distinguished name of the entry at which to start searching. If a value is specified for this parameter, then the webject value takes precedence over the property value specified in the adapter LDAP entry. The default for this parameter is the value specified for the searchBase property in the adapter LDAP entry. This is an optional parameter.
CONNECTION_ATTEMPTS
Defines the maximum number of times to attempt establishing a connection to an adapter before returning an error. The default value is 1. This parameter is optional.
If multiple INSTANCE parameter values are specified, the value of CONNECTION_ATTEMPTS defines the maximum number of times to iterate through the list of adapter instances.
CONNECTION_ATTEMPT_INTERVAL
Defines the amount of time, in seconds, to delay between connection attempts. The default value is 60 seconds. This parameter is optional.
If multiple INSTANCE parameter values are specified, the value of CONNECTION_ATTEMPT_INTERVAL defines the number of seconds to wait between the attempts to iterate through the entire list of adapter instances.
DBUSER
Specifies the name to use when logging in to the data repository. If this parameter is specified in this webject, the webject value takes precedence over any value specified in the credentials mapping settings or in the adapter LDAP entry. If this parameter is not specified here, it must be specified in the credentials mapping settings or in the adapter LDAP entry. For more information about credentials mapping, see the section
Credentials Mapping.
DEREF
Specifies how aliased objects should be handled during a search about the base object of the search. Valid values of this parameter are SEARCHING, FINDING, ALWAYS, and NEVER.
◦ The SEARCHING value aliases subordinates of the base object when searching the specified database, but not while locating the base object of the search.
◦ The FINDING value aliases while finding the base object of the search but not when searching subordinates of the base object.
◦ The ALWAYS value aliases both in searching the database and in locating the base object of the search.
◦ The NEVER value never aliases in searching nor in locating the base object of the search.
If a value is specified for this parameter, then the webject value takes precedence over the property value specified in the adapter LDAP entry. The default for this parameter is the value specified for the environment.java.naming.ldap.derefAliases property in the adapter LDAP entry.
If the property is not specified in the adapter LDAP, then the LDAP server default is used. This parameter is optional.
FILTER
Specifies the character string representing the search filter specific to an LDAP directory search. If a value is specified for this parameter, then the webject value takes precedence over the property value specified in the adapter LDAP entry. The default for this parameter is the value specified for the searchFilter property in the adapter LDAP entry. This parameter is optional.
GROUP_OUT
Identifies the name of the object set returned by the action. Currently, GROUP_OUT only returns a status message. This parameter is optional.
INSTANCE
Specifies the name of the adapter that executes the webject. Adapter names are defined when the adapter is configured for use in your Info*Engine environment. This parameter is required.
To connect to other adapters if a specific adapter is not available, this parameter can be multi-valued. Info*Engine attempts to connect to the adapters in the order given. If the first adapter specified in not available, the next adapter listed is tried, and so on, until a connection is made. If a connection cannot be established with any listed adapter, an error is returned.
In conjunction with this parameter, you can include two other parameters, CONNECTION_ATTEMPTS and CONNECTION_ATTEMPT_INTERVAL.
PASSWD
Specifies the password to use when logging in to the data repository. If this parameter is specified in this webject, the webject value takes precedence over any value specified in the credentials mapping settings or in the adapter LDAP entry. If this parameter is not specified here, it must be specified in the credentials mapping settings or in the adapter LDAP entry. For more information about credentials mapping, see the section
Credentials Mapping.
SCOPE
Indicates the scope of the search to be performed. Valid values are BASE, ONELEVEL, and SUBTREE:
◦ Setting the scope to BASE returns only the base entry of the search.
◦ Setting the scope to ONELEVEL returns the base entry of the search and all of its children.
◦ Setting the scope to SUBTREE returns the base entry of the search and the subtree.
If a value is specified for this parameter, then the webject value takes precedence over the property value specified in the adapter LDAP entry. The default for this parameter is the value specified for the searchScope property in the adapter LDAP entry. This parameter is optional.
SIZELIMIT
Specifies the maximum number of entries to be returned as a result of the query. If the specified limit is reached and the search is not complete, the found entries are returned and an IEPartialResultsException is thrown. If 0 is specified, all entries found are returned. The underlying LDAP directory may also impose a size limit restriction.
If a value is specified for this parameter, then the webject value takes precedence over the property value specified in the adapter LDAP entry. The default for this parameter is the value specified for the sizeLimit property in the adapter LDAP entry. If the property is not specified in the adapter LDAP, then the LDAP server default is used. This is an optional parameter.
This parameter has no effect if the specified value is larger than the underlying directory-specified limit.
TIMELIMIT
Specifies the maximum time in seconds allowed for the search. If the specified limit is reached and the search has not finished, the found entries are returned and an IEPartialResultsException is thrown. If 0 is specified, there are no time limit restrictions in effect for the search.
If a value is specified for this parameter, then the webject value takes precedence over the property value specified in the adapter LDAP entry. The default for this parameter is the value specified for the timeLimit property in the adapter LDAP entry. If the property is not specified in the adapter LDAP, then the LDAP server default is used. This parameter is optional.
This parameter has no effect if the specified value is larger than the underlying directory-specified limit.
Examples
With SCOPE set to ONELEVEL:
<%@page language="java" session="false"%>
<%@taglib uri="http://www.ptc.com/infoengine/taglib/core"
prefix="ie"%>
<ie:webject name="Query-Objects" type="ACT">
<ie:param name="INSTANCE" data="instance_name"/>
<ie:param name="BASE" data="ou=people, o=organization.com"/>
<ie:param name="ATTRIBUTE" data="cn"/>
<ie:param name="ATTRIBUTE " data="sn"/>
<ie:param name="GROUP_OUT" data="query"/>
<ie:param name="SCOPE" data="onelevel"/>
</ie:webject>
With SCOPE set to SUBTREE:
<%@page language="java" session="false"%>
<%@taglib uri="http://www.ptc.com/infoengine/taglib/core"
prefix="ie"%>
<ie:webject name="Query-Objects" type="ACT">
<ie:param name="INSTANCE" data="instance_name"/>
<ie:param name="BASE" data="ou=people, o=organization.com"/>
<ie:param name="ATTRIBUTE" data="cn"/>
<ie:param name="ATTRIBUTE " data="sn"/>
<ie:param name="GROUP_OUT" data="query"/>
<ie:param name="SCOPE" data="subtree"/>
</ie:webject>
With SCOPE set to BASE:
<%@page language="java" session="false"%>
<%@taglib uri="http://www.ptc.com/infoengine/taglib/core"
prefix="ie"%>
<ie:webject name="Query-Objects" type="ACT">
<ie:param name="INSTANCE" data="instance_name"/>
<ie:param name="BASE" data="ou=people, o=organization.com"/>
<ie:param name="ATTRIBUTE" data="cn"/>
<ie:param name="ATTRIBUTE " data="sn"/>
<ie:param name="GROUP_OUT" data="query"/>
<ie:param name="SCOPE" data="base"/>
</ie:webject>