Request Schema

Unlock seamless LDAP integration with the Nodinite LDAP Web API Request schema. This How To guide empowers you to construct robust, flexible requests in XML or JSON, and explains the schema for rapid, error-free development.

✅ Leverage a unified schema for both XML and JSON requests
✅ Integrate with BizTalk, custom code, or any platform
✅ Track, batch, and upsert operations for advanced scenarios
✅ Accelerate development with clear, pre-defined structures

You must send the Request to the Nodinite LDAP products using a pre-defined schema. Use the XSD format for XML messages, and follow the same definition for the JSON structure. As a developer, you can easily use and validate these requests in your solutions.

Note

For BizTalk implementations, a separate Property Schema (IS.BizTalk.Adapters.LDAP.PropertySchema_v1.0.xsd) is available for use in static and dynamic send ports when you need to provide connection information via context properties. See the Nodinite BizTalk LDAP Adapter Configuration documentation for details.

You do not need to install this schema in your BizTalk environment unless you create your own maps (.BTM files) or use custom-built pipelines/components that require it. The LDAP adapter performs all LDAP operations based on the available operations in the request schema.

The root record is named LDAP. The response root record is also named LDAP. This element contains two children:

• Batches
• PassThruContent

Diagram: the nesting of the Request message, from the LDAP root record down to the search criteria, operations, and properties of each entity.

The LDAP root record of the Request schema in the XSD.

Batches

The Batches element has two attributes and one child record:

guid

Each request must provide a unique tracking ID represented by the attribute guid. You must use a unique guid per message interchange (each call). The mandatory guid attribute aids error handling by identifying which batch failed. Each batch should have its own Universally unique identifier.

The guid you send is the same as the guid you receive in the response.

If you use C#, create a new GUID with:

System.Guid.NewGuid().ToString("D")

You can also review the following article.

returnResponseMessageOnExceptions

The optional parameter returnResponseMessageOnExceptions defaults to false. If errors occur, the system raises an application Exception that you must handle in your explicit error handler. Raising errors generally disrupts the flow.

We recommend that you set this attribute to true and handle the response message using standard conditional logic (if/case/when).

Note

JSON (LDAP Web API 4.0.1 and later): the property is named ReturnResponseOnExceptions and sits at the top level of the request, next to RequestId: "ReturnResponseOnExceptions": true. See the JSON examples.

You can use the different options during the design, development, and testing of solutions.

For BizTalk developers

If you use BizTalk and allow errors to be raised, the response message will be suspended in the BizTalk message box (BizTalkMsgBoxDb) and disrupt the flow. We do not recommend this approach.

returnResponseMessageOnExceptions = true.

returnResponseMessageOnExceptions = false.

For example, if you have an Orchestration and an error occurs, you must add an Exception block and handle the logic for retries. Since that code is part of a scope, you must add additional loops and logic to handle the error.

If you set returnResponseMessageOnExceptions to true, you can use an if clause and retry according to your logic without adding extra shapes. This approach accelerates your development and simplifies negative testing.

Batch

Each Request message can contain one or more Batches. Each Batch can contain one or more entities with one or more operations, repeated as needed and in the correct logical order.

A Request message with more than one Batch, each holding its own entities and operations.

Note

Each Batch holds one group of related operations. You must specify the order of operations in each batch.

Warning

If an exception occurs in a Batch, the system immediately aborts further execution.

To compensate for aborted or partial operations, keep your batches small, even though the adapter allows you to create large messages with unlimited operations.

Each Batch has these attributes:

transactionScopeOption

The system executes each batch within the Request in a transactional scope with options provided by the optional transactionScopeOption attribute.

No LDAP services currently honor the two-phase commit protocol. We provide this option for future use.

See also Transaction Scope Enum.

Available values (default Suppress):

• Required
• RequiresNew
• Suppress

transactionTimeOut

The optional attribute transactionTimeOut sets the period in seconds within which a transaction must complete. If not set, the default is 30 seconds. See TransactionScope Constructors.

Tip

You can use transactions and set the transactionTimeOut to abort operations that exceed your allowed time.

continueOnError

The optional continueOnError attribute (default false) lets you choose at design time to continue to the next Batch even if an operation fails. This feature enables the Nodinite LDAP product to support Upserts. For example, you can create one Request message with two batches: the first batch has the Insert operation, and the second batch contains the update operation. If the insert operation fails (for example, if the record already exists), the system still updates the record. You can use this feature for many other scenarios.

Batch Guid

You must provide a unique GUID per Batch. The system copies the GUID back to the response message. This feature lets you correlate the request Batch with the response data and enables even better tracking/Logging.

Example: A unique GUID for a batch.

With

The Nodinite LDAP products perform the requested operations based on the Set of objects returned from the search query. The search query uses the parameters in the With record.

The With record has the following structure:

Parameters for With.

CN

The optional CN attribute represents the common name to use in the query. Use this attribute when you require an exact match with the distinguished name.

Example:

Important

Do not provide the CN attribute for create operations.

Example of when to use CN: this scenario updates the description of Jane Doe. The CN part in the LDAP Catalogue is Jane Doe, and you want to update exactly this record.

Example: the CN attribute targets exactly one record.

Example of when NOT to use the CN attribute: when the query itself returns the set of objects to work on, do NOT provide the CN part, since the system extracts and uses the CN from the set of objects returned by the query.

OU

The optional OU attribute specifies which OU branch in the tree to bind to. For more information about OUs, see Organizational units.

Example of usage in the LDAP Adapter:

This binds to the logical department HQ. The HQ OU must exist in your LDAP Catalog for this query to succeed.

Note

You must explicitly write OU= as part of the value (right-hand side of =). This is because an OU in the catalog does not necessarily have to be an OU object. Other valid examples include OU="CN=Developers".

DC

The required attribute DC provides information on the domain component to bind to. For more information, see Object Names and Identities.

This is the top level of your LDAP tree.

Example of usage in the LDAP Adapter: This query searches from the top of the tree and traverses all nodes due to the searchScope option.

searchScope

The optional searchScope attribute sets the depth of the tree to traverse during search. If you don't set it, the default is Base. Valid values:

• Base
• OneLevel
• Subtree

Note

These values are case sensitive (as in XML).

See Specifying the Search Scope for more information.

expectedMatchCount

The expectedMatchCount attribute validates that your search criteria returns the expected number of records. If there is a mismatch, the Adapter aborts operations on the current batch to prevent unintended bulk operations.

Important

Critical Safety Feature

The expectedMatchCount attribute is your primary defense against accidental mass operations, especially for Delete operations that can permanently remove users, groups, or entire OU structures from Active Directory.

ALWAYS use expectedMatchCount for Delete operations to ensure you delete exactly what you intend.

Attribute Values

Note

The schema accepts only 0, a positive number, or *. Ranges such as 1-5 are not valid. To cap the number of objects instead, combine * with sizeLimit.

Examples

<!-- SAFE: Delete exactly one user -->
<With CN="CN=Jane Doe" OU="OU=Users" DC="DC=example,DC=com" expectedMatchCount="1"/>

<!-- SAFE: Update exactly 5 users matching criteria -->
<With OU="OU=Department" DC="DC=example,DC=com" searchFilter="(title=Manager)" expectedMatchCount="5"/>

<!-- SAFE: Select at least one matching record -->
<With OU="OU=Users" DC="DC=example,DC=com" searchFilter="(name=John*)" expectedMatchCount="*"/>

<!-- UNSAFE: No validation - could delete ALL users if filter is wrong -->
<With OU="OU=Users" DC="DC=example,DC=com" searchScope="Subtree"/>

Example of exception information when the number of records found did not match the numbers sought:

Example of exception information due to invalid value provided for parameter expectedMatchCount.

Exceptions

The adapter fails to operate for some use cases:

Create User

You can only create a user in exactly one OU. If you provide any value for expectedMatchCount other than 1, the adapter fails to operate.

returnProperties

The optional returnProperties attribute limits the number of properties returned in both SearchResult and OperationalResult. Only the properties with provided names are returned. Values are provided as a comma-separated list (no whitespaces) of the property names to return. If not provided, the system returns all properties.

If you provide DN as a requested property name, the system returns the full path (AdsPath/DN for ADSI) for the found object.

Warnings

The adapter may add Warning messages if you request properties that the adapter cannot find. Two internal operations occur in the adapter, and the warning messages are bound to these:

1. Search Part – returnProperties returns the matching attributes from search
2. Operation Part – returnProperties returns the matching attributes from the post-operation result.

sizeLimit

The optional sizeLimit attribute limits the number of objects to perform provided operations on. The default value 0 provides no limit. Otherwise, this value should be equal to or larger than expectedMatchCount. The system logs a warning and provides it in the result set if this condition is not met.

searchFilter

The optional searchFilter attribute can override or extend the standard filter used by the adapter when performing the query. Make sure to include the proper objectCategory/objectClass in your search if you are searching for something other than the predefined/hidden User/Group/OU. See also Search Filter Syntax.

Common valid examples:

• searchFilter="(name=j*)" – Limits the objects returned to those with names starting with the letter j.
• searchFilter="(objectCategory=Computer)(objectClass=computer)(!(operatingSystem=Windows 8*))" – Gets all computers that do not have Windows 8* as the operating system.

Entity

The LDAP adapter defines and groups supported operations per entity. The LDAP Request Batch supports the following entities (record names as in the schema):

Each operation always has a name and may include additional parameters, which may or may not be required depending on the operation.

The With record defines the selection criteria for the query, and is required for the User, Group, and OrganizationalUnit entities. The With part always receives a corresponding SearchResult record in the Response message.

Properties

The Create and Update operations of the User, Group, and OrganizationalUnit entities may have a Properties record.

This collection can contain named (name) attributes with values (value) to set in Insert and Update operations.

The optional contentType attribute has the following allowed values:

The following attributes use contentType:

• jpegPhoto
• thumbnailPhoto

Missing parameter Example

If an operation requires an argument by the schema definition and you do not provide it, the operation within the batch fails and the response message may contain an exception message with details.

Invalid operation provided

If you send an invalid or unsupported operation to the LDAP Adapter, the system does not execute that operation and aborts the batch.

The response message may contain an exception message with details.

PassThruContent

The LDAP adapter supports submitting ANY XML-based data as part of the Request. Embed this data within the PassThruContent element.

You should use a qualified namespace with a prefix on all elements. The system returns the same data as part of the Response message.

This feature means you do not need an orchestration and a multipart messagetype to construct the next message in the message chain! Also, using this technique, you can construct the map more easily.

The adapter already supports XSLT on the response, so you can get the final result back from the adapter.

You should put the “Any” data in a namespace. The new PassThruContent record is optional (0..1) in the schemas.

Next Steps

• Review the Response Schema for output structure
• Explore User Management for practical examples
• Learn about Logging for traceability

Related Topics

• LDAP Web API Overview
• Developer Guide
• Schema Management
• Group Management
• BizTalk LDAP Adapter Configuration