In the first part of this series, we looked at using Playbooks to move demand management assets from one server to another. Whilst Playbooks is a very useful tool, it does have one limitation in that it moves all the chosen settings over, so if you wish to export a single EPT and its PDPs, you’re out of luck.
Luckily Microsoft released another tool as part of its ‘solution starters’ series that allows the selective exporting and importing of demand management assets. The solution starter consists of two components, the DMExport utility that is used to export the settings and the DMImport code and scripts that contains all that is needed to turn the exported items into a SharePoint 2010 feature for installation.
As with all solution starters, there are two components available, the compiled code mainly ready for deployment in your environment, and the full source code so you can see how it actually works and use it as the basis for future enhancements. For most solution starters, the documentation is either sufficient or the solution simple enough to install and use. Unfortunately in the case of the DMImport /DMExport solution starter, the documentation is a bit lacking and you need to do a fair bit to get it up and running, so hence this post
Before we start, you will need to download both the Deployment and Source zip files from the solution starter site. The starters are updated on a very regular basis, so for the purposes of this post, I am using the release from late December 2010.
2. Install and use the DMExport Utility
In order to export the demand management assets, it is necessary to install a small utility on the server you wish to export from. Whilst the solution starter provides the source, the easiest way is to use the neatly packaged setup.exe that is provided in the deployment project. This will install the DMExport utilise to the c:\Program Files\Microsoft\DMExport directory ready for use.
Just like Playbooks, when you first run the DMExport tool it will request the address of the Project Server instance to script the configuration settings out of. Once a connection is established the GUI will display the various demand management items that can be selected and this is where the real advantage of the tool comes in.
Unlike playbooks where you script all the workflow settings, the DMExport tool allows you to choose what you wish to export and will attempt to determine the relevant associated assets to include. Now from my experience the autocomplete is pretty good but has one flaw, it forgets to associate the workflow status PDP’s (Proposal Stage Status in the above screenshot), which if you don’t include, the restore will fail as it is a mandatory field when creating an Enterprise Project Type.
Before hitting the export button, make sure to populate the ‘Feature Name’ which will eventually become the name of the SharePoint feature that is used to install the assets on the target server and to set the location that the data will be exported to.
Once the export process has completed, you should see a set of files like those below in your export directory.
These files contain the relevant data for the items selected for export and will eventually be turned into a SharePoint feature.
3. Building the DMImport components
The DMImport component consists of two parts, an import library that reads the exported files from above and updates the relevant components within Project Server 2010, and some scripts used to build a SharePoint feature that is used to deploy the assets. The feature when activated calls the import library via a feature receiver.
Before the DMImport scripts can be used it is necessary to build the import library and register it on the destination server. The source code zip file contains everything needed to build the import library. Simply open the project in Visual Studio 2010 and build the project. Once the build is complete the following DLL should be created:
To register the DLL, use the gacutil.exe file located in the DMImport\Deployment directory of the source zip file and the following command:
Gacutil.exe /i <path>\Microsoft.SDK.Project.Samples.ImportDemandManagement.dll
4. Build the feature
Creating the feature itself that contains all the demand management assets is relatively simple. To start, copy the files created in the export location to a new directory on the restore server as well as the contents of the \Solution Starters\EPT_Export_Import\DMImport\Deployment directory .
To build the feature, in the SharePoint 2010 Management Shell, enter the following command:
./InstallFeature.ps1 <directory of the exported assets, including a trailing />
This will kick off the PowerShell script and generate the feature by copying the exported files and building a feature.xml that pulls them all together and associates the feature receiver built above.
If all goes well you should see something like this in the output:
The red error is fine, it is caused by running the script in a SharePoint Management shell instead of a plain old PowerShell shell.
On seeing the ‘Done.’ above, the feature will be generated and installed on the destination server. To check, go to Site Actions > Site Collection Features on the destination server and the newly generated feature will be there awaiting activation.
You may notice the associated image is broken, there looks to be a bug in the script which I haven’t looked at yet.
5. Activate and use the feature
The demand management assets will not be installed until the feature is activated. On clicking Activate, SharePoint will activate the feature receiver and via the import library create the relevant assets inside Project Server. The activation process can take a while to complete, especially if you are importing a lot of assets. In addition, the first time you activate the feature it will create a special logging document library on the destination server that is used to store logging information and a set of XML files describing the changes made.
The latter are very important if you later choose to deactivate the feature as they outline how to roll back the changes and return the Project Server back to how it was before activation.
Again, the documentation is not exactly clear on the library, but for reference it is created at http://<server>/<projectserverinstancename>/DMImport.
6. Deactivating and removing the feature
Should you need to roll back the changes and uninstall the feature, simply Deactivate the feature via Site Actions > Site Collection Features, then in the SharePoint Management Shell enter the following command:
Uninstall-spfeature –Identity <featureName>