The Request sent to the Nodinite LDAP products must follow the structure of a pre-defined schema. This schema is created in XSD format and applies to messages in XML format. The JSON structure follows the same structure, hence, this schema should be easy to use and follow as a developer regardless of format.
|BizTalk Message Type||
This schema is not required to be installed in the BizTalk environment unless you create your own maps (.BTM files) or use custom built pipelines/pipeline components where this schema is needed. All LDAP operations performed by the LDAP adapter are 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 has two children:
The batches element has three children:
- guid - Provides means for end to end tracking
- returnResponseMessageOnExceptions - determine type of response when errors occur
- Batch - A collection of work to be performed
Each request must provide a unique tracking ID represented by the attribute
guid. This guid should be unique per message interchange (each call). The mandatory guid attribute aid the error handling process by providing guidance on which batch failed. Each batch should have its own unique id.
Using C#? Then use the following syntax to create a new GUID:
You can also review the following article
The optional parameter
returnResponseMessageOnExceptions has Default=false. This means that any errors that occur will render an application Exception that you must deal with in your explicit error handler. Raising errors generally disrupts the flow.
We recommend that you provide the value
truefor this attribute and deal with the response message using "normal" conditional (if/case/when) logic instead
Usage of the different options are intended for developers/solution architects during the design and development/testing of solutions.
If you are using BizTalk and allow errors to be raised, the response message will be suspended in the BizTalk message box (BizTalkMsgBoxDb) and definitely disrupts the flow. This is not recommended.
For example, if you have an Orchestration and there is an error, you will need to add an Exception block and deal with the logic for retries. Since that code is part of a scope, you will need additional loops and logics to deal with the error.
Using the value
true for the *returnResponseMessageOnExceptions attribute give you the ability to use an if clause instead and retry according to your logic without adding tons of shapes. This recommendation will make your development faster and your negative tests will be much easier to perform.
Each Request message can contain one or more Batches. Each Batch can contain one or more entities with one or more operations repeated as you like and what is semantically and logically the right order.
In order to compensate for aborted/partial operations you should keep your batches small, even though the adapter provides you the ability to create large messages with unlimited set of operations(!).
Each batch within the Request is executed within a transactional scope with options provided by the optional
There are no LDAP services available today that honours the two phase commit protocol. This option is provided for future use.
See also Transaction Scope Enum
Available values are:
The optional attribute
transactionTimeOut sets the period in seconds within which a transaction must complete. Default, if not set, is 30 seconds. ServiceBehaviorAttribute.TransactionTimeout Property
Tip: You can use transactions and set the transactionTimeOut if you want to abort operations that takes longer than the time you allow for.
continueOnError attribute provides you with the design time choice to continue to the next Batch even if an operation fails. This ability of the Nodinite LDAP product in reality means support for
Upserts. For example, you 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 due to that the record already exists, then the record will still be updated. You may utilize this ability for many other scenarios as well.
You must provide a unique GUID per Batch. The GUID will be copied back to the response message. This feature means that you can correlate the request Batch with the response data and also facilitate even better tracking/Logging.
The Nodinite LDAP products perform the requested operations based on the Set of objects returned from the search query. The search query is based on the parameters in the
CN attribute represents the common name to use in query. This attribute should be used when exact match with distinguished name is required.
Example of when NOT to use the
In this example you should NOT provide CN part since the CN part will be extracted and used from the set of objects returned by the query.
OU attribute can be used to specify 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 will bind to 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 due to the fact that an OU in the catalog does not necessarily be an
OU object. Other potentially valid examples of usage is OU=”CN=Developers”
The required attribute
DC provides information on domain component to bind to.
For more information:
This is the top level of your LDAP tree.
Example of usage in the LDAP Adapter: This query will search from the top of the tree and traverse all nodes due to the searchScope option.
126.96.36.199 searchScope The depth of the tree to traverse during search. Valid values are:
Note: These are case sensitive (as everything in XML)
See http://msdn.microsoft.com/en-us/library/ms677937(v=vs.85).aspx for additional information.
expectedMatchCount attribute informs the Adapter about the number of records intended to be found. If there is a mismatch the Adapter will abort operations on current batch. No check is performed if this value is not provided. Valid values if provided 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
Exceptions The adapter will fail to operate for some use cases:
Create User It is only valid to create a user in exactly one OU. If you provide any other value for expectedMatchCount but 1 the adapter will fail to operate.
returnProperties attribute can be used to limit the number of properties returned in both
OperationalResult. Only the properties with provided names will be returned.
Values are provided using a comma separated list (no whitespaces) of the property names to return. Default if not provided will return all properties.
DN as requested property name will return the full path (AdsPath/DN for ADSI) for found object.
Warnings The adapter may add Warning messages if you ask for properties that the adapter cannot find. There are 2 internal operations happening in the adapter and the warning messages are bound to these.
- Search Part – returnProperties will return the matching attributes from search
- Operation Part– returnProperties will return the matching attributes from post operation . the result.
sizeLimit attribute can be used to limit the number of objects to perform provided operations on. Default value 0 provides no limit on the number of objects. Else, this value should be equal or larger than
expectedMatchCount. A warning from the adapter will be logged and provided in the result set if this condition is not met.
searchFilter attribute can override and/or extend the standard filter in use by the adapter when performing the query. Make sure to include the proper objectCategory/objectClass in your search if you are searching for something else than predefined/hidden in User/Group/OU. See also http://technet.microsoft.com/en-us/library/cc978015.aspx.
Common valid examples of usage: searchFilter="(name=j*)" – Limit the objects returned to the ones with name starting with the letter j.
searchFilter="(objectCategory=Computer)(objectClass=computer)(!(operatingSystem=Windows 8*))" – Get all computers that that does not have Windows 8* as operating system.
The operations supported by the LDAP adapter are defined and grouped per entity. The LDAP Request Batch has support for the following entities:
- Users - Managing users are further exemplified in the [User Management] guide.
- Groups - Managing groups are further exemplified in the [Group Management] guide.
- Schemas - Managing the Schema is further exemplified in the [Schema Management] guide.
- Organization Units (OU) - Managing Organizational Units (OUs) are further exemplified in the [OU Management] guide.
- AD - Managing the AD is further exemplified in the [AD Management] guide.
Image example of entities defined by the Request schema (xsd):
The specific operations available per entity are given by the examples chapter.
The available operations always have a name and might include additional parameters that depending on operation may or may not be required.
The different entities available may or may not have a
With record. The
With record defines the selection criteria to be used for the query. The
With part will always get a corresponding
SearchResult record in the Response message.
Entities User and Group - Insert and Update operations may have a
This collection can contain named (
name) attributes with values (
value) to set in Insert and Update operations.
contentType attribute has a restriction with the following values:
- String (Default value)
String - values are written as is without modification.
RAW - Not used in version 1.0
LoadFromByteArray - Content is provided in a 64BaseEncoded Byte array
LoadFromFile – Loads content from file. Make sure to provide a highly available file share when using this feature.
The following attributes uses contentType:
188.8.131.52 Missing parameter Example If an operation takes an argument that is required by the schema definition and you do not provide that argument the operation within the batch will fail and the response message may contain an exception message with details like:
184.108.40.206 Invalid operation provided If an invalid/not supported operation is sent to the LDAP Adapter that operation will not be executed and the batch will be aborted.
The response message may contain an exception message with details like:
9.2.5 PassThruContent The LDAP adapter has support for submitting ANY xml based data as part of the Request. This data in embedded within the PassThruContext element.
You should use a qualified namespace with prefix on all elements. The same data will be returned part of the Response message.
This means you do not need an orchestration and a multipart messagetype to construct the next message in the message chain! Also, using this technique the map will be easier to construct.
The adapter already has support for XSLT on the response, meaning you can get 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.