- 10 minutes to read

Request Schema

Unlock seamless LDAP integration with the Nodinite LDAP Web API Request schema. This 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.
File IS.BizTalk.Adapters.LDAP.Request_v1.0.xsd
Target Namespace http://integrationsoftware.se/BizTalk/Adapters/LDAP/Request/1.0
Root Node LDAP
BizTalk Message Type http://integrationsoftware.se/BizTalk/Adapters/LDAP/Request/1.0#LDAP

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:

Request

Batches

The batches element contains three children:

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'.

guid 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).

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.

stateDiagram Client --> LDAP LDAP --> Client

returnResponseMessageOnExceptions = true.

sequenceDiagram Client->>+Nodinite LDAP: Request Nodinite LDAP->>-BizTalk MsgboxDB: Error - Suspend Message Nodinite LDAP->>Client: Exception

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.
Batch Request

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.

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:

  • 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 ServiceBehaviorAttribute.TransactionTimeout Property.

Tip

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

continueOnError

The continueOnError attribute 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.

Batch Guid

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:
With 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:

JSON XML
"With: { "CN": "CN=John Doe" <With CN="CN=Jane Doe"

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. CN Example

Example of when NOT to use the CN attribute: In this example, 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: https://en.wikipedia.org/wiki/Active_Directory#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: http://technet.microsoft.com/en-us/library/cc977992.aspx

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 searchScope attribute sets the depth of the tree to traverse during search. Valid values:

  • Base
  • OneLevel
  • Subtree

Note

These values are case sensitive (as in XML).

See Specifying the Search Scope for more information.

expectedMatchCount

The optional expectedMatchCount attribute tells the Adapter how many records you intend to find. If there is a mismatch, the Adapter aborts operations on the current batch. If you do not provide this value, the system performs no check. Valid values are 0..n. Use a number for explicit count or * for at least one.

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 http://technet.microsoft.com/en-us/library/cc978015.aspx.

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:

Image example of entities defined by the Request schema (xsd):

The examples chapter provides the specific operations available per entity.

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

Some entities may or may not have a With record. The With record defines the selection criteria for the query. The With part always receives a corresponding SearchResult record in the Response message.

Properties

Entities User and Group - Insert and Update operations 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:

  • String (Default value)
  • RAW
  • LoadFromByteArray
  • LoadFromFile

String - The system writes values as is without modification.

RAW - Not used in version 1.0

LoadFromByteArray - Provide content as a 64BaseEncoded Byte array.

LoadFromFile – The system loads content from a file. Make sure to provide a highly available file share when using this feature.

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 PassThruContext 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 Step