Request Architecture

The XML-based requests used to invoke procedures in Microsoft Provisioning Framework (MPF) and the other components of Microsoft Provisioning System (MPS) are the starting point for each provisioning transaction.

What a Request Is

MPF executes provisioning tasks in response to requests. MPF implements requests as XML documents.

There are two types of requests, simple and trusted:

How a Request Works

Requests are submitted to Microsoft Provisioning Framework (MPF) by a client. Each request contains one XML procedure that invokes the functionality of an underlying provider or another procedure. Each procedure must conform to the XML schema registered in MPF.

You can submit requests by calling methods in the client. This approach supports provisioning within a local data center (synchronous communication without callback). The client has two interfaces, IProvEngine and IProvQueue. IProvEngine contains methods for submitting real-time requests to a provisioning engine. IProvQueue has methods to submit and manage requests for processing by a queue manager. Both IProvEngine and IProvQueue use separate methods to submit untrusted and trusted requests.

When MPF executes a request, it generates an executeXml node internally to pass the request data as XML to the called procedure in the respective provider. When a provider finishes processing a request, it returns an XML response node (containing either a successful result or an error) to the calling user.

Example of a Request

The following example shows a request, including the procedure that is called by the request.

<request xmlns:xsl="http://www.w3.org/1999/XSL/Transform">
  <data>
	<organizations>
	<organization name="OrgA" type="primary"/>
	<organization name="OrgB" type="secondary"/>
	<organization name="OrgC" type="secondary"/>
	</organizations>
  </data>
  <procedure>
	<!-- Procedure call to SignupOrg-->
	<execute namespace="New Namespace" procedure="New Request">
	<before source="data" destination="executeData" mode="merge"/>
	<after source="executeData" destination="data" mode="merge"/>
	</execute>
  </procedure>
</request>

In the preceding request, the data node supplies the source data. The procedure starts with a call (not shown) to SignupOrg. SignupOrg is the downstream procedure that receives the selected names in the response returned by the execution step, the call to New Request (execute). The before node merges the data from the data node into the executeData node for SignupOrg. The after node merges information from New Request's executeData node into the response data. (In this simple example, the returned data is the same as that which was originally passed by the before node.)

Note: Do not include namespace inside XML request, no matter it is created manually by user or automatically by MPS SDK. Otherwise, the XML request will not pass Schema validation. This following request will not pass schma validation.

<?xml version="1.0" encoding="iso-8859-1" ?> 
<request xmlns="http://provisioning.microsoft.com/MPF" xmlns:xsl="http://www.w3.org/1999/XSL/Transform">
		<data>
				<preferredDomainController>ad01.fabrikam.com</preferredDomainController>
				<path>LDAP://OU=Hosting,DC=fabrikam,DC=com</path>
		</data>
		<procedure>
				<execute namespace="Exchange 2007 Provider" procedure="RebuildOfflineAddressBook">
						<before source="data" destination="executeData" mode="merge" />
						<after source="executeData" destination="data" mode="insert" />
				</execute>
		</procedure>
</request>

Instead, use needs to remove the namespace inside XML request like:
<?xml version="1.0" encoding="iso-8859-1" ?> 
<request xmlns:xsl="http://www.w3.org/1999/XSL/Transform">
		<data>
				<preferredDomainController>ad01.fabrikam.com</preferredDomainController>
				<path>LDAP://OU=Hosting,DC=fabrikam,DC=com</path>
		</data>
		<procedure>
				<execute namespace="Exchange 2007 Provider" procedure="RebuildOfflineAddressBook">
						<before source="data" destination="executeData" mode="merge" />
						<after source="executeData" destination="data" mode="insert" />
				</execute>
		</procedure>
</request>
Example of Processed Data Sent to the Provider

The following example shows the content of the executeXML document that MPF passes to the provider.

<executeXml>
  <context>
	<transactionContext 
	transactionId="{CE8E0B55-B582-4D95-A796-92FDDD8228B7}" />
	<executeContext procedure="Write Request" procedureExecId="2" 
	providerSource="Provisioning.SimpleProvider.1" namespace="Test Namespace" 
	type="write" />
  </context>
  <executeData>
	<primaryOrg>OrgA</primaryOrg>
	<secondaryOrg>OrgB</secondaryOrg>
	<secondaryOrg>OrgC</secondaryOrg>
  </executeData>
</executeXml>

After the provider receives this data, it passes the data into the executeDatanode of the Write Request.

Example of a Response

The following example shows the response to the processed request.

<response>
  <data>
	<organizations>
	<organization name="OrgA" type="primary"/>
	<organization name="OrgB" type="secondary"/>
	<organization name="OrgC" type="secondary"/>
	</organizations>
	<orgSignup>
	<primaryOrg>OrgA</primaryOrg>
	<secondaryOrg>OrgB</secondaryOrg>
	<secondaryOrg>OrgC</secondaryOrg>
	</orgSignup>
  </data>
</response>

The response shows the merged organization data in <data> and the selected names in <orgSignup>.

For information on what a request is and how it is implemented in Microsoft Provisioning System, see What a request is and Request implementation in Microsoft Provisioning System. For information on procedures, see Procedure Architecture. For information on namespaces, see Namespace Architecture.

Request Implementation in Microsoft Provisioning System

You can submit requests to Microsoft Provisioning Framework (MPF) either from Delegated Administration Console or by submitting XML directly or through a custom user interface (UI). Delegated Administration Console implements requests by getting the XML of the request from one of the XML templates provided in Microsoft Provisioning System, incorporating the data that is entered in the Delegated Administration Console user interface, and then passing the request to MPF.

The request, including the procedure in the request, must conform to the XML schema implemented by Microsoft Provisioning Framework (MPF). The templates used by Microsoft Provisioning System conform to the schema. The templates do not show how the data is merged into the request, however. Even if your organization is not planning on using Delegated Administration Console, it is recommended that you install it, turn debug mode on, and use all of the functionality. The resulting debug file includes the requests submitted to MPF to carry out a function, as well as the responses to the requests. This can give you valuable information about how requests can be implemented.

For more information on using the debugging options, see Working with debugging options and Configure debugging options in Delegated Administration Console Help.

Note

Delegated Administration Console implements only a subset of the functionality supported by the namespaces, procedures, and providers included in Microsoft Provisioning System. To see all procedures available with Microsoft Provisioning System, ensure that all providers and namespaces are installed, and then use Provisioning Manager to view the available procedures of each namespace.

[an error occurred while processing this directive]