Request Schema

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.

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

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:

• Batches
• PassThruContent

Batches

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

guid

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.

the guid sent is the same as the guid returned

Using C#? Then use the following syntax to create a new GUID:

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

You can also review the following article

returnResponseMessageOnExceptions

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 true for 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.

For BizTalk developers

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.

returnResponseMessageOnExceptions= true

*returnResponseMessageOnExceptions= false*

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.

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 you like and what is semantically and logically the right order.

> Exceptions in a **Batch** immediately aborts further execution

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(!).

transactionScopeOption

Each batch within the Request is executed within a transactional scope with options provided by the optional transactionScopeOption attribute.

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:

• Required
• RequiresNew
• Suppress

transactionTimeOut

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

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

Batch Guid

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.

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 is based on 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 query. This attribute should be used when exact match with distinguished name is required.

Example:

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

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

Example of when NOT to use the CN attribute: 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.

9.2.3.2 OU

The optional 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”

9.2.3.3 DC The required attribute DC provides information on 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 will search from the top of the tree and traverse all nodes due to the searchScope option.

9.2.3.4 searchScope The depth of the tree to traverse during search. Valid values are:

• Base
• OneLevel
• Subtree

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.

9.2.3.5 expectedMatchCount The optional 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 expectedMatchCount

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.

9.2.3.6 returnProperties The optional returnProperties attribute can be used to limit the number of properties returned in both SearchResult and 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.

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

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

9.2.3.7 sizeLimit The optional 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.

9.2.3.8 searchFilter

The optional 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.

Entity

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.

9.2.4.1 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 a restriction with the following values:

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

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:

• jpegPhoto
• thumbnailPhoto

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

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