How to: Import an Application Definition from XML
The Business Data Catalog now supports two types of XML application definition files: Model and Resource. A Model application definition file contains the base XML metadata for a system. A Resource file enables you to import or export only the localized names, properties, and permissions, in any combination. Following are the types of Resource files:
LocalizedNames Contains localized names for the metadata objects in a particular locale. When you import this file, its information is merged with the existing metadata in the metadata repository. If a localized name for the locale already exists, it is overwritten with the information from the LocalizedNames file.
Properties Contains properties for metadata objects. When you import this file, its information is merged with the existing metadata in the metadata repository. If a property already exists, its value is overwritten with the information from the Properties file.
Permissions Contains access control lists (ACLs) for metadata objects. When you import this file, its information is merged with the existing metadata in the metadata repository. However, if an access control entry (ACE) already exists for an object, its value is overwritten with the information from the Permissions file. For example, if the existing application definition only includes User A who has access to Entity A and then you import a Permissions file that only includes User B who has access to Entity A, then the old ACL for Entity A will be deleted and a new ACL created for User B.
If you import a Model file for an application, Business Data Catalog will overwrite any existing metadata for that application. However, if you import Resource files containing localized names, properties, or permissions, in any combination, Business Data Catalog will perform a merge operation. It will simply merge the contents of the Resource file with the already existing metadata for that application.
This is extremely useful in certain situations. To illustrate this point, let's say you have already imported an application definition file for a complex enterprise resource planning (ERP) system. Now let's consider three situations:
There is a change in the back-end connection information. To update the connection information, you can create a simple Properties Resource file that includes only the changed properties in the LobSystemInstance object and then import it. Business Data Catalog will merge this information with the existing LobSystemInstance properties and if a property already exists, its value will be overwritten with the new information from the Resource file.
Your company diversified into a new region and your application now has to support a new localized language. In this case, you can create a LocalizedNames Resource file that contains only the localized names for this new language and then import the file. Business Data Catalog then merges this information with the existing metadata, which easily resolves this issue.
A franchise needs to use your application in their environment. In this case, they can create a Permissions Resource file that contains only the ACLs for the users in their franchise and then import it. Business Data Catalog overwrites the existing ACLs with the new information, which solves this issue.
Importing a new resource file is a better approach than updating the Model file. If you update the Model file by adding the localized names or properties, Business Data Catalog will delete the existing metadata and overwrite it with the new information. This may not always be desirable and could involve additional testing and effort. For example, if you update the Model file, the Business Data Catalog deletes all metadata objects and their IDs and therefore, would require a full crawl of the metadata objects for search.
Important
A single application definition file can contain any combination of Model and Resource files. SharePoint Central Administration supports this in the Import and Export user interface (UI) and the object model supports this using bitwise OR (|) operators.
You can use the Administration object model to import metadata from XML files. This allows you to automate the addition of application definitions to the Business Data Catalog. The following code example shows you how to use the ImportPackage method of the LobSystem object to import metadata.
Note
You can use the bitwise OR operator ( | ) to pass in multiple PackageContents values per export and import.
Example
The following code example shows how to use the ImportPackage method of the LOBSystem object to import metadata for a system.
Prerequisites
Make sure a Shared Service Provider has already been created.
Obtain the AdventureWorks2000.XML file from MSDN Download Center.
Replace the SQL Server name in the XML file and the XML file location in the code example with actual values.
Replace the constant value EnterYourSSPNameHere in the code with the name of your Shared Resource Provider.
Project References
Add the following Project References in your console application code project before running this sample:
Microsoft.SharePoint
Microsoft.SharePoint.Portal
Microsoft.Office.Server
System.XML
using System;
using System.Collections.Generic;
using System.Text;
using System.IO;
using Microsoft.Office.Server.ApplicationRegistry.Administration;
using Microsoft.Office.Server.ApplicationRegistry.Infrastructure;
using WSSAdmin = Microsoft.SharePoint.Administration;
using OSSAdmin = Microsoft.Office.Server.Administration;
namespace Microsoft.SDK.SharePointServer.Samples
{
class GetStartedAndCreateSystem
{
const string yourSSPName ="EnterYourSSPNameHere";
const string XMLFileLocation = "EnterXMLFileLocationHere";
static void Main(string[] args)
{
SetupBDC();
ImportLobSystemFromXML();
Console.WriteLine("Press any key to exit...");
Console.Read();
}
static void SetupBDC()
{
SqlSessionProvider.Instance().SetSharedResourceProviderToUse(yourSSPName);
}
public static void ImportLobSystemFromXML()
{
if (File.Exists(XMLFileLocation))
{
FileStream xmlStream = new FileStream(XMLFileLocation, FileMode.Open, FileAccess.Read);
ParseContext parseContext = new ParseContext();
ApplicationRegistry.Instance.ImportPackage(xmlStream, parseContext, PackageContents.Model | PackageContents.Properties);
}
else
{
throw new ArgumentException(string.Format("Specified path is invalid [{0}]", XMLFileLocation));
}
}
}
}