LDAP functions in Jitterbit Integration Studio
Introduction
LDAP (Lightweight Directory Access Protocol) is a protocol that allows you to search and update a directory. It is supported by numerous directory servers such as Microsoft Active Directory and Netscape Directory Server. A directory usually contains information about users and network resources, but can contain any kind of data. These functions allow scripts and transformations to connect to a directory using LDAP. These functions are used independently of the LDAP connector, which has similar functionality built into the connector.
The use pattern follows these steps:
LDAPConnect
: Establishes a connection to the serverLDAPAdd
,LDAPReplace
,LDAPRemove
,..: Queues actions to be takenLDAPExecute
: Executes the queue on the server
For searching, you can follow this pattern:
LDAPConnect
: Establishes a connection to the serverLDAPSearch
: Executes the search on the server and returns the result
Set LDAP passwords programmatically
As of Harmony version 9.9, LDAP passwords can be set using these LDAP functions. The password needs to first be converted to binary before it can be set. (The password may require enclosing in double quotes prior to the conversion to binary, as Active Directory requires values to be enclosed in double quotes.) This script fragment shows how this could be accomplished:
LDAPConnect("directory.company.example.com:10389", "admin", $adminpassword, 0);
$plain = '"J1tterb1t!@#"';
$pwd = StringToHex($plain);
$i=0;
$newPwd = "";
While($i < Length($pwd)/2,
$newPwd = $newPwd + Mid($pwd, $i * 2, 2) + "00";
$i = $i+1;
);
$newPwd = HexToBinary($newPwd);
LDAPReplace("unicodePwd", $newPwd);
LDAPExecute("CN=wright,CN=Users,DC=company,DC=example,DC=com");
ArrayToMultipleValues
Declaration
string ArrayToMultipleValues(array arr)
Syntax
ArrayToMultipleValues(<arr>)
Required parameters
arr
: An array with values to be used to populate a multiple-valued LDAP attribute
Description
Signals that an array should be used to populate a multiple-valued LDAP attribute when mapping to an LDAP target. The array is converted to XML and interpreted when the LDAP server is written to.
Examples
// Create two LDAP attributes using an array
arr = Array();
// Length(arr) will always return the index of
// the next-after-last element of an array
arr[Length(arr)] = "First instance";
arr[Length(arr)] = "Second instance";
// The array will be converted to the string
// "<JB_Array><it>First instance</it><it>Second instance</it></JB_Array>"
result = ArrayToMultipleValues(arr);
LDAPAdd
Declaration
bool LDAPAdd(string ldapType, string ldapValue)
Syntax
LDAPAdd(<ldapType>, <ldapValue>)
Required parameters
ldapType
: The LDAP record or attribute typeldapValue
: The value to be added for the type
Description
To use this function, the LDAPConnect
function must first be used to establish a connection with the LDAP directory.
After a connection is established, the LDAPAdd
function is used to add entries and attributes to the connected LDAP directory. The value is added to the node specified in the LDAPExecute
function, which should be called immediately afterwards to have the changes take effect.
See also the LDAPConnect
and LDAPExecute
functions.
Examples
// Adding a user entry to a directory:
LDAPAdd("objectClass", "user");
LDAPAdd("cn", "wright");
LDAPExecute("CN=wright,CN=Users,DC=company,DC=example,DC=com");
// Adding attributes to a user:
LDAPAdd("description", "Thinks a lot.");
LDAPExecute("CN=wright,CN=Users,DC=company,DC=example,DC=com");
LDAPConnect
Declaration
bool LDAPConnect(string hostname, string user, string password[, int mode, long port])
Syntax
LDAPConnect(<hostname>, <user>, <password>[, <mode>, <port>])
Required parameters
hostname
: Hostname of an LDAP server to connect to; can include a port, such asdirectory.example.com:10389
user
: User name to connect to the LDAP hostpassword
: Password to use to connect to the LDAP host
Optional parameters
-
mode
: Connection mode; one of:0
: Non-secure connection; default port: 3891
: Secure connection; default port: 3892
: Secure connection using LDAP over SSL; default port: 636
-
port
: Port to use to connect to the LDAP host (-1
indicates to use the default LDAP ports)
Description
Connects to a directory using LDAP.
See also the LDAPExecute
function.
Tip
When using this command, use a Jitterbit project variable to store the password in a secure manner that will not be visible when the script is being viewed.
Examples
// Connects to an LDAP server using hostname:port, username, password, mode
connected = LDAPConnect("directory.company.example.com:10389", "admin", $adminpassword, 0);
LDAPDeleteEntry
Declaration
bool LDAPDeleteEntry(string distinguishedName)
Syntax
LDAPDeleteEntry(<distinguishedName>)
Required parameters
distinguishedName
: An LDAP distinguished name to be removed from the currently connected server
Description
To use this function, the LDAPConnect
function must first be used to establish a connection with the LDAP directory.
After a connection is established, the LDAPDeleteEntry
function is used to remove an entry specified by a distinguished name.
See also the LDAPConnect
and LDAPExecute
functions.
Examples
LDAPDeleteEntry("CN=wright,CN=Users,DC=company,DC=example,DC=com");
LDAPExecute
Declaration
bool LDAPExecute(string distinguishedName)
Syntax
LDAPExecute(<distinguishedName>)
Required parameters:
distinguishedName
: An LDAP distinguished name on the currently connected server
Description
To use this function, the LDAPConnect
function must first be used to establish a connection with the LDAP directory.
After a connection is established, the LDAPExecute
function is used to execute one or more modifications (add, remove, replace) that have previously been specified with the LDAPAdd
, LDAPRemove
, or LDAPReplace
functions.
See also the LDAPConnect
and LDAPExecute
functions.
Examples
// Adding LDAP entries and executing them
LDAPAdd("description", "Thinks a lot.");
LDAPReplace("telephoneNumber", "(510) 555 1000");
LDAPExecute("CN=wright,CN=Users,DC=company,DC=example,DC=com");
LDAPRemove
Declaration
bool LDAPRemove(string ldapType, string ldapValue)
Syntax
LDAPRemove(<ldapType>, <ldapValue>)
Required parameters
ldapTyp
: The LDAP attribute typeldapValue
: The value to be removed for the specified attribute type
Description
To use this function, the LDAPConnect
function must first be used to establish a connection with the LDAP directory.
Once a connection is established, the LDAPRemove
function is used to remove an attribute of a specified type and with a specified value.
If the attribute type of that value is not found, an error is thrown. See also the LDAPConnect
and LDAPExecute
functions.
Examples
// Removing an LDAP entry and executing it
LDAPRemove("telephoneNumber", "(510) 555-1000");
LDAPAdd("telephoneNumber", "(510) 555-2000");
LDAPExecute("CN=wright,CN=Users,DC=company,DC=example,DC=com");
LDAPRename
Declaration
bool LDAPRename(string distinguishedName, string newRDN[, string newParent, bool deleteOldRDN])
Syntax
LDAPRename(<distinguishedName>, <newRDN>[, <newParent>, <deleteOldRDN>])
Required parameters
distinguishedName
: The path of the directory entry (distinguished name) to be renamednewRDN
: The new relative distinguished name
Optional parameters
newParent
: The distinguished name of the new parent of this entry; the default is emptydeleteOldRDN
: Iftrue
, the old relative distinguished name will be deleted; the default isfalse
Description
To use this function, the LDAPConnect
function must first be used to establish a connection with the LDAP directory.
Once a connection is established, the LDAPRename
function is used to change the distinguished name of an entry in the connected directory.
See also the LDAPConnect
and LDAPExecute
functions.
Examples
LDAPRename("telephoneNumber", "telephoneNumberHome");
LDAPExecute("CN=wright,CN=Users,DC=company,DC=example,DC=com");
LDAPReplace
Declaration
bool LDAPReplace(string ldapType, string ldapValue)
Syntax
LDAPReplace(<ldapType>, <ldapValue>)
Required parameters
ldapType
: The LDAP record or attribute typeldapValue
: The new value to be set for the type
Description
To use this function, the LDAPConnect
function must first be used to establish a connection with the LDAP directory.
Once a connection is established, the LDAPReplace
function is used to replace an existing attribute's value with a new value.
See also the LDAPConnect
and LDAPExecute
functions.
Note
If you use LDAPReplace
to replace an existing attribute's value with a new value in an Active Directory, the text may be converted to a different result than the entry. For example, François would return FrançOis. For more information on adding UTF-8 support, see the LDAP entry in Edit the configuration file (jitterbit.conf).
Examples
// Replacing an LDAP entry and executing it
LDAPReplace("telephoneNumber", "(510) 555-1000");
LDAPExecute("CN=wright,CN=Users,DC=company,DC=example,DC=com");
LDAPSearch
Declaration
string LDAPSearch(string path, string filter, int detail, string attribute1[, ... string attributeN])
Syntax
LDAPSearch(<path>, <filter>, <detail>, <attribute1>[, ... <attributeN>])
Required parameters
path
: The distinguished name used as the base of the searchfilter
: A query string search filter, as defined by RFC 4515**-
detail
: Details to be returned:0
: Pass to return a simple string that is the first attribute found that matches the filter1
: Pass to return an XML representation of the search results. This can be set to a data element using theSet
function and then accessed later usingGet
and an XPath query using theSelectSingleNode
function.2
: Pass to return a 2-dimensional array, where each row represents an LDAP entry and where the row elements are the values of the attributes. Access the elements using theGet
function.
-
attribute,... attributeN
: An attribute to be included in the search result (in other words, the attribute you are searching for). Additional attributes can be specified; separate them by commas.
Description
To use this function, the LDAPConnect
function must first be used to establish a connection with the LDAP directory.
Once a connection is established, the LDAPSearch
function is used to search within the connected directory.
See also the LDAPConnect
and LDAPExecute
functions.
Controlling Jitterbit variables
These Jitterbit variables affect the search:
Variable | Value(s) | Description |
---|---|---|
jitterbit.scripting.ldap.scope | 0 | Limit the scope of the query to the base-entry only |
1 | Search all entries in the first level below the base-entry, excluding the base-entry (default) | |
2 | Search the base-entry and all entries in the tree below the base | |
jitterbit.scripting.ldap.include_dn_in_results | true | Include the distinguished name in the search result (default: false ) |
jitterbit.scripting.ldap.use_paged_search | true | Use a paged search; useful for retrieving large result sets (default: false ) |
jitterbit.scripting.ldap.max_search_results | n | Limit the number of search results to n results; a default is usually set by the LDAP server (default unlimited: -1 ) |
jitterbit.scripting.ldap.return_null_if_no_results | true | Make LDAPSearch() return null if the search does not return any results (default: false) |
Examples
// Connecting to an LDAP server using a password set
// in a global variable ("$ldapPassword") and then performing a search
LDAPConnect("directory.company.example.com", "ghvwright", $ldapPassword, 0);
directorySearchResults = LDAPSearch("CN=Users,DC=company,DC=example,DC=com",
"(&(objectCategory=person)(objectClass=user))", 1, "name", "whenCreated",
"description", "telephoneNumber");