MPS Import Namespace API

  • Article

This document provides the details of the application programming interface (API) for the MPS Import namespace included with the Microsoft Provisioning System (MPS) in . Contained herein are descriptions of the procedures of this namespace along with method input parameters and return values. In addition, example Extensible Markup Language (XML) requests are provided along with typical XML responses that the provisioning system returns after a request is submitted to MPS and tasks are completed.

Developers should use this API document as a reference when creating XML requests that migrate users and organizations into the MPS system, providing that they have already been physically migrated into an MPS hosting Active Directory directory service structure.

Overview

The MPS Import namespace exposes a set of Microsoft Provisioning Framework (MPF) public named procedures for importing users and organizations into an existing MPS hosting Active Directory structure.

The current state of provisioning Hosted Exchange users relies on the Hosted Exchange Namespace APIand several underlying namespaces and providers. It is assumed that users are created through this namespace to ensure synchronization with the various system entities that track users and organizations. These entities are:

  • Active Directory

  • MPS Resource Manager

  • MPS Plans Database

However, there are certain scenarios where the dependency on these systems causes problems in real-world deployments, as follows:

  • A user or an organization was created by MPS code, but not by Hosted Exchange code, for example with previous versions of the Exchange solution, Web hosting solution, or Data hosting solution.

  • Users and organizations already exist prior to the deployment of Hosted Exchange and these entities need to be "migrated" into the Hosted Exchange system.

There are currently no migration tool sets provided to customers for migrating users in a prescribed fashion, since the requirements for migration vary considerably from service provider to service provider.

The purpose of the MPS Import namespace is to provide a set of APIs that will enable "last-mile" migration of users and organizations into the MPS system. Moreover, the MPS Import namespace solves a small, well-defined chunk of the migration problem by requiring that organizations and users (and their mailboxes) already be physically migrated into an MPS hosting Active Directory structure using tools such as ADMT and the Exchange Mailbox Migration Wizard. Then, the procedures of the MPS Import namespace can solve the problem of configuring these objects for hosting, importing these objects into the Resource Manager, and importing these objects into the Plans Database.

Background Concepts

This section provides conceptual material for using the MPS Import namespace.

Import Prerequisites

The MPS Import namespace only attempts to provide the final configuration and import of organizations and users into the MPS Hosted Exchange provisioning system. As such, there are a number of prerequisites that must be satisfied before the procedures can be used to import a user or organization.

General Prerequisites

  • A hosting container prepared with Managed Helpers::InitializeAdForHosting must exist.

  • All Managed Namespaces (MPS 1.0) must be installed and configured.

  • The Hosted Exchange Namespace must be installed and configured.

  • The Customer Plans Database must be installed and configured.

  • Exchange Resource Manager Namespace and Exchange Resource Manager Ex Namespace must be installed and configured.

  • Exchange mail store resources must be added to the Resource Manager pool.

Organization Prerequisites

The organization must exist in the hosting container at the proper level in the hierarchy dependent upon its role - reseller or customer. For example:

Domain

OU=Hosting

User Prerequisites

The user must exist in the organization container that was created by the Hosted Exchange::CreateBusinessOrganization procedure or previously prepared with one of the following:

  • MPS Import::ImportOrganization procedure.

  • MPS Import::EnableOrganizationForHosting.

For example, the user must exist in the following structure:

Domain

OU=Hosting

Dependencies

The MPS Import namespace is implemented as MPF namespaces and therefore depends on MPF, standard providers, and non-provider namespaces. The following is a list of critical namespaces upon which the MPS Import namespacee depends, and which are installed with MPS core components:

  • CoreRMO

  • BlockModelRMO

  • Active Directory Provider

  • Preferred DC Active Directory Provider

  • Managed Active Directory Namespace

  • Managed Hosting Namespace

The functionality of the MPS Import namespace also depends on interaction with other namespaces as well. Also, you install the MPS Import namespace with the MPS Deployment Tool. Therefore, when you design your MPS deployment configuration with the MPS Deployment Tool, you should queue the following namespaces for installation to support the functionality of the MPS Import namespace:

  • SQL Admin Provider

  • Exchange Provider

  • Exchange Resource Manager namespace

  • Exchange Resource Manager Ex namespace

  • Hosted Exchange namespace

  • Managed Helpers

Public Methods

The MPS Import namespace implements several public named procedures to facilitate the importing of existing organizations and users into a Hosted Exchange shared environment. Primarily this functionality is provided by two procedures, as follows:

  • MPS Import::ImportOrganization - Creates a child OU structure, creates security groups, set ACLs, sets group memberships, sets otherWellKnownObjects, allocates the organization in Resource Manager, creates a SMTP domain, and creates a plan database record in a single transaction.

  • MPS Import::ImportUser- Renames user, preserves existing sAMAccountName, set ACLs, sets group memberships, creates a plan database record, creates (or imports) an Exchange mailbox, applies plan settings to the mailbox, and allocates the mailbox to MPS Resource Manager in a single transaction.

The end result of both of these procedures is that the user or organization is configured exactly the same as it would be if it had been created through the Hosted Exchange namespace.

To facilitate more complex migration scenarios where all of these steps are unnecessary in a single transaction, the underlying functionality of these import procedures are exposed as discreet public procedures that can be called separately, as follows:

  • MPS Import::EnableOrganizationForHosting - Creates child OU structure, creates security groups, prevents DACL inheritance, set ACLs, sets group memberships, and sets otherWellKnownObjects in a single transaction.

  • EnableUserForHosting- Renames user, preserves existing sAMAccountName, prevents DACL inheritance, set ACLs, and sets group memberships

  • MPS Import::EnableCustomerForPlans - Ensures a record in the plans database for an organization or user.

  • MPS Import::AllocateExistingMailbox - Allocates an existing mailbox in Resource Manager. The mailbox is allocated to the store where it currently exists. In the parent organization has insufficient resources on that store then resources are added to accommodate. This procedure must be run as a highly privileged account such as Enterprise Administrator.

  • MPS Import::CreateMailbox- Creates a mailbox using the setting of a valid plan. Also applies prescriptive attribute stamping to the user. Optionally will allocate to Exchange RM if the <allocateOrg/> element is supplied.

  • MPS Import::ApplyMailboxPlan - Applies the settings of a valid plan to an existing mailbox. Also applies prescriptive attribute stamping to the user. Does not interact with resource management.

This also facilitates "repair" type scenarios such as repairing an organization that has had the _Private container removed by accident.

In addition some procedures from existing namespaces are used in the import user or import organization process, as follows:

  • Hosted Exchange::AddAvailablePlans - defines what plans are available to an organization's users.

  • Exchange Resource Manager::AllocateOrganization - allocates storage space in Resource Manager for an organization.

  • Exchange Resource Manager::AllocateMailbox - allocates a mailbox to resource manager.

  • Exchange Resource Manager Ex::AllocateConsumerUserMailbox - allocates a mailbox to resource manager.

Applies To

  • Hosted Messaging and Collaboration version 3.5