Procedure Architecture

The XML-based procedures implemented using Microsoft Provisioning Framework (MPF) and the other components of Microsoft Provisioning System are the core elements of all provisioning transactions.

What a Procedure Is

In Microsoft Provisioning Framework (MPF), a procedure is a blueprint for executing the steps of a provisioning request. A procedure can be one of the following:

• A declaration of a provisioning action executed by a provider. This type of procedure must be defined in the namespace for that provider.

• A sequence of calls to other MPF procedures.

Every request contains a single procedure (which can, in turn, contain calls to other procedures). MPF executes each step in the order in which it appears. The XML structure of a procedure is defined in a provider namespace or derived from a combination of lower-level procedures. For specialized needs, you can write a custom procedure that chains calls to other procedures, usually from multiple providers.

Procedures are grouped into namespaces. In order for procedures to be available to incoming requests, their namespace must be registered in the configuration database.

Using Provisioning Manager or Configuration Database WMI Provider, you can configure the following procedure properties.

Table: Procedure Properties

Property	Description
Procedure name	Identifies the name of the procedure. You can change a procedure name at any time. Modifying a procedure name can cause problems if other procedures call it, however. If you modify a procedure name, be sure to update the XML of all other procedures that call that procedure.
Access type	A procedure is either public or private (default). A public procedure can be called from an incoming request outside of MPF, but a private procedure can only be called from within MPF.
Request type	Specifies which functions a procedure can invoke: Read - Invokes only an execute function to process the request with no rollback function. Write - Invokes both an execute function to process the request and a rollback function to implement after a failure. Two-phase enabled - Invokes both an execute function to process the request and a rollback function to implement after a failure for Provider namespace procedures that perform updates subject to rollback.
Execute as	Specifies the user credentials with which MPF invokes the procedure. Only credentials previously defined in Provisioning Manager can be selected. This option does not appear for read-only namespaces, such as the Error Provider namespaces. In addition, the field is not enabled unless at least one user credential exists in the configuration database. For more information on Execute as, see Basic Authentication in Authentication.
Audit	Specifies whether procedure calls are saved to the audit log. This setting corresponds to the auditEnabled attribute in the namespace XML procedure node. In addition to marking a procedure for audit, you can also configure the audit level for procedure calls. For more information, see Administering provisioning engines in Provisioning Manager Help.
Auto-generate performance counters	Specifies whether to automatically implement performance counters for the procedure. Note, however, that a performance counter does not show up in the performance monitor until the first time a procedure runs.
Save data for rollback	Specifies whether to automatically save the input data that enables the rollback of a failed procedure. Important It is recommended that you not change this property. Doing so can cause data and system corruption if a transaction fails.
XML	Implements procedure steps for calling a provider or another procedure. You can modify a procedure's XML from Provisioning Manager, but this practice is not recommended. Instead, modify and test the XML outside of the production environment, then import it once testing is complete.
Security	Specifies who can execute each procedure and determines the permissions to allow or deny each user. By default, permissions propagate from a namespace to its procedures, so changes to permissions apply to all procedures. You can override this default behavior for individual procedures, however.

How a Procedure Works

Procedures in Microsoft Provisioning System work in the following way. First, a request is submitted to Microsoft Provisioning Framework (MPF) by a client. Each request contains an XML procedure that invokes either the functionality of an underlying provider or another procedure. Each procedure implemented in Microsoft Provisioning System must be part of a namespace registered in MPF and must define a schema for an Extensible Stylesheet Language (XSL) transformation. Each request submitted to MPF must conform to the XML schema and must contain the data required to implement the procedure.

Example of Procedure

The following example shows a definition of a procedure:

  <procedure name="New Request" type="write" access="public"> 
    <execute namespace="Test Namespace" procedure="Write Request"> 
      <forEach name="organization" root="data"  
        path="organizations/organization"/> 
      <before source="organization" destination="executeData"> 
        <xsl:template match="organization[@type='primary']"> 
          <primaryOrg> 
            <xsl:value-of select="@name"/> 
         </primaryOrg> 
        </xsl:template> 
        <xsl:template match="organization[@type='secondary']"> 
         <secondaryOrg> 
            <xsl:value-of select="@name"/> 
          </secondaryOrg> 
        </xsl:template> 
      </before> 
      <after source="executeData" destination="data"  
        destinationPath="orgSignup" mode="merge"/> 
    </execute> 
  </procedure> 

This example works as follows:

• The XML of New Namespace contains the procedure New Request.

• The <execute> node calls Write Request, which is a procedure that belongs to the Test Namespace.

• The <forEach>, <before>, and <after> nodes define the XSL transformation:

  • The <forEach> node restricts the range of the search to the </data/organizations/organization> node of the request.

  • The <xsl> nodes in <before> select the values for the name attribute from the source (that is, the <organization> nodes of type primary and secondary) and pass them to the destination (the <executeData> node of the Write Request procedure). Because this operation supplies data to the Write Request procedure, it occurs before Write Request is executed.

  • The <after> node retrieves the name values from the Write Request <executeData> node and merges them into the </data/orgSignup> node of the response.

Procedure Implementation in Microsoft Provisioning System

Procedures reside in the namespaces of Microsoft Provisioning Framework (MPF). You can access namespaces by using Provisioning Manager, which is the Microsoft Management Console (MMC) snap-in used to administer Microsoft Provisioning Framework (MPF).

MPF uses the XML schema for the procedure element in both namespaces and requests. Most procedures, except those of read-only namespaces, can be modified to meet specific functionality requirements. Custom procedures can also be added to all namespaces except read-only namespaces. Read-only namespaces, which are indicated by the red highlighting for the namespace in the console tree of Provisioning Manager, are critical to the operation of MPF.

Each of the procedures of a namespace is registered with the configuration database when the namespace is registered with MPF. You can use Provisioning Manager to register a namespace, by either creating or importing it. You can also register it from the command line by running ProvNamespace.exe.