Overview

You can use this Snap to search for items in Active Directory. It also provides options to select the scope and provide filter attributes to effectively return search results.

The attributes of table are populated in the suggestions list based on the existing distinguished name in Active Directory. The table consists of all the fields that can be used as filter attributes to perform search and effectively return the results.

Snap Type

The Active Directory Search Snap is a Read-type Snap that reads the matched entries based on the filter criteria.

Prerequisites

A valid Active Directory Basic Auth account.
Existing distinguished name.

Support for Ultra Pipelines

Works in Ultra Pipelines.

Behavior change

Previously the Page Size field worked similar to the Limit field, that is, it set the limit on fetching records instead of fetching all the records.
The Active Directory Search Snap output now displays the number of records that you specify in the Limit field under Settings. If your Pipelines use the Snap with the Page Size field, they may fail to execute if the downstream Snap expects the same count. To retrieve all the records, configure the Snap with default settings, that is, Limit: 0 and Page Size: 1000.

Snap Views

Type	Format	Number of views	Examples of Upstream and Downstream Snaps	Description

Type

Format

Number of views

Examples of Upstream and Downstream Snaps

Description

Input

Document

Min: 0
Max: 1

File reader followed by any file Parser followed by Structure.

Existing distinguished name, Filter attributes (Filter keys, Filter values).

Output

Document

Min: 1
Max: 1

Any file Formatter followed by File Writer.

The output data and the searched entries based on the specifed existing distinguished name.

Error

Error handling is a generic way to handle errors without losing data or failing the Snap execution. You can handle the errors that the Snap might encounter while running the Pipeline by choosing one of the following options from the When errors occur list under the Views tab. The available options are:

Stop Pipeline Execution: Stops the current pipeline execution when the Snap encounters an error.
Discard Error Data and Continue: Ignores the error, discards that record, and continues with the rest of the records.
Route Error Data to Error View: Routes the error data to an error view without stopping the Snap execution.

Learn more about Error handling in Pipelines.

Limitations and Known Issues

None.

Snap Settings

Asterisk (*): Indicates a mandatory field.
Suggestion icon (): Indicates a list that is dynamically populated based on the configuration.
Expression icon (): Indicates whether the value is an expression (if enabled) or a static value (if disabled). Learn more about Using Expressions in SnapLogic.
Add icon (): Indicates that you can add fields in the field set.
Remove icon (): Indicates that you can remove fields from the field set.

Field	Field Type	Description
Label* Default Value: Search Example: Active Directory Search	String	Specify a unique name for the Snap.
Existing distinguished name* Default Value: None Example: CN=User	String/Expression	Specify the LDAP API references an LDAP object by its distinguished name (DN). A DN is a sequence of relative distinguished names (RDN) connected by commas. An RDN is an attribute with an associated value in the form attribute=value, normally expressed in a UTF-8 string format. The typical RDN attribute types include: DC = domainComponent, CN = commonName, OU = organizationalUnitName,O = organizationName, STREET = streetAddress, L = localityName,ST = stateOrProvinceName, C = countryName, UID = userid. A distinguished name for an LDAP entry can be represented as: CN=AbcUser,CN=Users,DC=server,DC=company,DC=com. In this example, to refer to the entire user list, you can remove the initial attribute, CN=AbcUser. This field is applicable only to existing users. If the user does not exist, create an entry using the Create Entry Snap first. You can also use special characters in the distinguished name. Learn more about Using Special Characters in Distinguished Name.
Page size* Default Value: 1000 Example: 500	Integer	Specify the size of the page to receive search results. The maximum value accepted by Active Directory is 1000. Refer to https://msdn.microsoft.com/en-us/library/ms180880(v=vs.80).aspx for more information.
Limit Default Value: 0 Example: 5	Integer	Specify the number of search records to be fetched from the Active Directory.
Scope type Default Value: SUBTREE_SCOPE Example:	Dropdown list	Specify the scope type to search against. The options available include: SUBTREE_SCOPE - A subtree search (or a deep search) includes all child objects as well as the base object. ONELEVEL_SCOPE - A one-level search is restricted to the immediate children of a base object, but excludes the base object itself. This setting can perform a targeted search for immediate child objects of a parent object. OBJECT_SCOPE - A base search (OBJECT_SCOPE) limits the search to the base object. The maximum number of objects returned is always one. This search is useful to verify the existence of an object for retrieving group membership.
Filter Attributes	Field set	Specify the key-value pairs to filter the search results.
Filter keys	String/Expression/Suggestion	The suggested filter attributes based on the provided Existing distinguished name property.
Filter values	String/Expression	The corresponding values of the suggested filter key to perform an effective search.
Returning Attributes	Use this field set to define the attributes that should return in the search results.
Attribute Keys Default Value: None Example: objectClass, DistinguishedName (member;range=1500-1600), cn	String/Expression/Suggestion	Specify the attribute keys that should return in the search results.
Group results Default Value: Deselected	Checkbox	Select to group the output result in a single array.
Pass through Default Value: Deselected	Checkbox	Select to include the entire input data in the Snap's output. The Snap includes this data within the $original field in the output.
Default Value: Execute only Example: Validate & Execute	Dropdown list	Select one of the following three modes in which the Snap executes: Validate & Execute: Performs limited execution of the Snap, and generates a data preview during Pipeline validation. Subsequently, performs full execution of the Snap (unlimited records) during Pipeline runtime. Execute only: Performs full execution of the Snap during Pipeline execution without generating preview data. Disabled: Disables the Snap and all Snaps that are downstream from it.

Additional Information

The following table indicates the output the Search Snap returns for a given Distinguished name.

Distinguished name value	Returns

Distinguished name value	Returns
CN=groupname,CN=Users,DC=server,DC=company,DC=com	Details about that group.
CN=Users,DC=server,DC=company,DC=com	Details about all items in Users under that domain.
DC=server,DC=company,DC=com	Details about all objects on that server domain.

Using Special Characters in Distinguished Name

You can include special characters in the Distinguished name and Existing distinguished name fields. You do not have to prefix the following special characters with an escape character:

Forward slash (/)
Backward slash (\)
Plus (+)
Double quote (“)
Less than symbol (<)
Greater than symbol (>)
Semicolon (;)

If an escape character is prefixed, the Snap reads it, else, it prefixes it to the special character to correctly process the data.

Using Special Characters

For instance, you need to specify a distinguished name, such as CN=man/eesh,CN=Users,DC=ad1,DC=clouddev,DC=snaplogic,DC=com, where the common name man/eesh contains a special character. This Snap supports both scenarios:

If the special character is prefixed with an escape character. For example, CN=man\/eesh.
If no escape character is used. For example, CN=man/eesh,

In both cases, the Snap generates the same output during Pipeline validation, as shown in the image below. This ensures existing Pipelines do not break in either case.