XML Schema for Procedures
Microsoft. Provisioning Framework (MPF) uses the XML schema for the procedure element in both namespaces and requests. The following code fragment summarizes the basic structure of procedure.
<procedure description=".." name=".." type=".." access=".." perfEnabled=".." auditEnabled=".." saveDataForRollback=".."> <try>0..unbounded <execute namespace=".." procedure=".." impersonate=".." sensitive=".." trusted="..">0..unbounded <executeData>0..1</executeData> <forEach name=".." root=".." path=".." ifNull="..">0..unbounded</forEach> <when source=".." sourcePath=".." select=".." case=".."> 0..unbounded</when> <repeat source=".." sourcePath=".." ifNull="..">0..unbounded<repeat> <before source=".." sourcePath=".." destination=".." destinationPath=".." mode=".." ifNull=".." allowNullTransform=".."> 0..unbounded</before> <after source=".." sourcePath=".." destination=".." destinationPath=".." mode=".." ifNull=".." allowNullTransform="..">0..unbounded</after> </execute> <queue namespace=".." procedure=".." queueSuspended=".." impersonate=".." sensitive=".." trusted="..">0..unbounded <!-- Same children as <execute> --> . . . </queue> <transform>0..unbounded <!-- Same children as <execute> --> . . . </transform> <select name=".." source=".." sourcePath=".." defaultCase=".." ifNullCase="..">0..unbounded <where value=".." case="..">0..unbounded</where> </select> <try>0..unbounded <!-- Recursive node --> </try> <catch>0..unbounded <!-- Recursive node --> </catch> </try> <catch>0..unbounded <!-- Same children as <try> --> . . . </catch> <select name=".." source=".." sourcePath=".." ifNullCase=".." defaultCase="..">0..unbounded <where value=".." case="..">0..unbounded</where> </select> <procedureData>0..1</procedureData> </procedure>In this code fragment:
- The root node procedure registers the procedure in the namespace and defines any XSL transformations. The attributes of procedure are used only in namespaces, not in requests.
- The execute and queue nodes (both optional) encapsulate procedure calls and XSL transformations for data used in processing steps. The execute nodes transform data for immediate processing by a provisioning engine. The queue nodes transform batch data for delayed processing by a queue manager.
- The transform nodes (optional) resemble execute and queue nodes, but they transform data not associated with a procedure step.
- Transformations can use forEach, when, repeat, before, and/or after nodes (all optional). The forEach nodes define execution loops and ranges of data to include. The when nodes check for the presence of an element, attribute, or value (of an element or attribute) in one of the procedure's select nodes. The associated execution block is executed whenever the condition in a when node evaluates to true. The repeat nodes execute procedures a specified number of times. The before node identifies the source and destination of data for operations performed before the execution step. The after node identifies these for operations performed after the execution step.
- When error handling is required, execute, queue, select, and transform nodes (all optional) can be wrapped in a try node that acts on error information passed to it by the corresponding catch node, which extracts the error from the procedure's response XML. The select nodes (optional) encapsulate conditional checking that takes place before the procedure executes. The child where nodes represent the conditions to check for. A select node can have multiple where nodes, but only the first where node evaluating to true is processed.
- Finally, the procedureData node (optional) supplies free-form XML content to the procedure. The contents of procedureData are locally scoped and therefore not exposed to the calling procedure.
During transaction processing, the calling procedure operates on data from the request's data node. Calls to providers are embedded in the procedure's execute nodes. before nodes copy and transform the content of data and pass it to an executeData node. When the Provisioning Engine passes the request to the provider, the provider scans the incoming execute node for input child nodes. When the provider finishes processing, it stores the output (if any) to child nodes of an executeData node and returns the data to the caller. after elements copy and transform data from executeData back to the data node. These steps are repeated until all the execute nodes in the request have been processed.
In addition to calling a provider, an execute node can call a non-final procedure. The processing flow is similar to the one just described except that the execute node can have a forEach node that calls a provider multiple times to iterate over a range of data.
Provider procedures can be called individually, or a procedure can aggregate calls to multiple providers. For example, suppose you need a provider that adds a row in a SQL table, then sends a SOAP request to a service such as Microsoft. Hotmail.. In this situation, you could write a custom procedure that calls ExecSQL and SoapRequest.
Procedures in Namespace Definitions
The following code fragment summarizes the basic structure of a procedure when it is part of a namespace definition. For more information on the namespace element, see XML Schema for Namespaces.
<namespace name=".." providerSource=".." description=".." readOnly=".."> <procedure description=".." name=".." type=".." access=".." perfEnabled=".." auditEnabled=".." saveDataForRollback="..">1..unbounded <Schema>1..unbounded</Schema> <!-- Child nodes for execute/queue steps and try/catch handling --> . . . </procedure> <providerContext>0..1</providerContext> </namespace>The Schema nodes (optional) encapsulate schema for a procedure's input and/or output data. Provisioning Manager can be configured to validate input data from a request procedure against the procedure's namespace schema; for more information, see Provisioning Engines. If there is a conflict during transaction processing, the request will fail.
Procedures in Requests
The following code fragment summarizes the basic structure of a procedure when it is part of a request. For more information on the request element, see XML Schema for Requests.
<request> <globalData>0..1</globalData> <data>0..unbounded</data> <context>0..1</context> <procedure>1..1 <!-- Child nodes for execute/queue steps and try/catch handling --> . . . </procedure> </request>In this code fragment, the globalData node is used only for queued requests.
Note A namespace can have multiple procedures, but a request has only one.
See Also
Developing Custom Namespaces, Developing Custom Providers, Procedure Examples, Provisioning Schema
Top of Page
) 1999-2002 Microsoft Corporation. All rights reserved.