Creating XML requests

The providers implemented in Microsoft Provisioning Framework (MPF) each require specific data and an action to invoke a particular function. The XML request contains the data and action that are passed to MPF.

Structuring XML requests

Requests must meet the following requirements:

One or more actions must be specified in the <procedure> element, which identifies the namespaces and procedures to be executed in the request. The <procedure> element can also contain any special processing instructions for this information.
The data must be specified for the <executeData> element, including the optional and required input for the request, as well as the elements used for processing instructions. The contents of an <executeData> node are only visible to the parent execute node. In contrast, the contents of the optional <data> node are visible to all execute nodes in the request.
The file should have the following opening tag: <?xml version="1.0" encoding="utf-8" ?>
All procedures expect to have both the caller's account and the MPFServiceAcct available to the procedure. To run a procedure as the caller, the procedure must use impersonate="1". In addition, to call these procedures from namespaces that you create, you must provide the correct security context. For more information on security contexts in MPF, see Security contexts.
An untrusted request can contain only a single procedure. A trusted request can contain multiple procedures.

Important

Although Active Directory is not case sensitive for elements such as the Lightweight Directory Access Protocol (LDAP) path, XML is case sensitive. To ensure that the procedure executes appropriately, specify all tags, elements, and data using uppercase and lowercase letters exactly as shown in the XML examples. For additional guidelines on how to use XML, see the Microsoft Web site (http://www.microsoft.com/).

Specifying data in requests

The <executeData> element of a procedure implements all required and optional input for the procedure. You can provide input for the <executeData> element in one of the two following ways:

You can specify the input in the <data> element, which is located outside of the procedure.
Making use of the information in the <data> element requires a <before> tag to make the data available to the <executeData> element of a procedure. Input provided in the <data> block is available to all procedures in the request that use the appropriate <before> tag.
You can specify the input directly in the <executeData> element of the procedure.
Providing information directly in the <executeData> element makes it available only to the <execute> element of the individual procedure in which it is specified, not to any other procedures in the request.

Most of the examples of XML requests provided in this section are structured to implement input by incorporating it in the <executeData> element.

Examples using each of the two data elements

The following examples show the two different ways of providing input for procedures.

Example providing input in the <data> element

<request>
  <data>
	<name>Reseller1</name>
	<policyName>reseller</policyName>
	<container>LDAP://ou=Hosting,dc=contoso,dc=com</container>
	<description>The contoso reseller</description>
  </data>
  <execute namespace="namespace name" procedure="procedure name">
	<before source="data" destination="executeData" mode="merge"/>
  </execute>
</request>

Example providing input directly in the <executeData> element

<request>
  <execute namespace="namespace name" procedure="procedure name">
	<executeData>
	<name>Reseller1</name>
	<policyName>reseller</policyName>
	<container>LDAP://ou=Hosting,dc=contoso,dc=com</container>
	<description>The contoso reseller</description>
	</executeData>
  </execute>
</request>

Obtaining XML code for specific requests

You can create XML requests by copying the XML from one of two sources:debug files or XML examples. A description of each follows.

Debugging files
You can turn on the debugging option of Delegated Administration Console, and then perform the actions that correspond to the requests you want to capture. The debugging function captures each of the requests, as well as each of the responses. It then writes each request and response to individual files and places them in the Debug folder. The requests show the XML transformations of the request. This is the recommended method for capturing the XML for requests supported in Delegated Administration Console. Even if you do not plan to use Delegated Administration Console, you can install the program, run it using debugging mode, and then uninstall Delegated Administration Console.

For more information on using debugging options, see "Working with debugging options" and "Configure debugging options" in Delegated Administration Console Help.
XML examples
You can copy the XML from examples of each request shown in appropriate sections for each of the non-provider namespaces. These show the XML transformations of the request and generally show all available options. This is the recommended method for capturing the XML for requests that are not supported in Delegated Administration Console.

The Microsoft Provisioning Framework Software Development Kit (SDK) contains additional resources to help you understand how XML requests and procedures are implemented in MPF. For more information on the SDK and how to use it, see Microsoft Provisioning Framework SDK and documentation.

Customizing and saving XML requests

After copying the XML requests from the appropriate source, you can modify them to meet your requirements. After creating each XML document, including incorporating any required and optional input in the request contained in the document, save the document as an .xml file, using the Unicode - Codepage 65001 encoding option.