“Look ma, no hands!” : Automating Install and Uninstall of Packages!

No, your eyes are not deceiving you! Since the Summer’13 release, you can now automate the installation and uninstall of managed packages! The main use case for this I guess is for those building Continuous Integration build systems using Apache Ant. Where they are deploying code which requires dependent packages to be installed before deployment.

In addition this is also a useful API for building package management tools and UI’s to help administrators install other packages you offer via a kind of package menu! Thus I’ll show how to use it from my Apex Metadata API wrapper.

From Ant via <installPackage> and <uninstallPackage> Tasks

So first lets look at doing this via Ant. You’ll need to download the Force.com Migration Toolkit from your Tools page. I’ve placed the ant-salesforce.jar file in a lib subfolder as per the reference in the sample below.

You can only deploy the new InstalledPackage component type that describes the package to install, on its own. Though it still requires the usual folder structure and package.xml file before using the usual sf:deploy Ant task. To make things easier, I’ve put together a couple of Ant marcos to distill its use a bit further. You can download the ant-salesforce.xml file containing the macro. After that its as easy as this….

<project name="installdemo" default="build" basedir=".">
	<!-- Load standard properties -->	
	<property file="${basedir}/build.properties"/>	
	<!-- Import macros around sf:deploy to install/uninstall packages -->
	<import file="${basedir}/lib/ant-salesforce.xml"/>
	<!-- Default target -->	
	<target name="build">		
		<!-- Install the package with namespace packagea --> 
		<installPackage namespace="packagea" version="1.0" packagePassword="fred1234" 
		   username="${sf.username}" password="${sf.password}"/>
		<!-- Uninstall the package with namespace pacakgea -->
		<uninstallPackage namespace="packagea" 
		   username="${sf.username}" password="${sf.password}"/>		
	</target>	
</project>

Note: The packagePassword attribute is optional.

From Apex via Metadata API Apex Wrapper

This is how its done via the Metadata API directly, in Apex (though the following is more or less the same in Java). Note fullName in the samples below is used to pass the namespace of the managed package being referenced.

		// Install packageA, then pacakgeB
		MetadataService.InstalledPackage installedPackageA = new MetadataService.InstalledPackage();
		installedPackageA.versionNumber = '1.0';
		installedPackageA.password = 'fred1234';
		installedPackageA.fullName = 'packagea';
		MetadataService.InstalledPackage installedPackageB = new MetadataService.InstalledPackage();
		installedPackageB.versionNumber = '1.0';
		installedPackageB.fullName = 'packageb';
		MetadataService.AsyncResult[] results = createService().create(
		    new List<MetadataService.Metadata> { installedPackageA, installedPackageB });		

And to uninstall…

		// Uninstall packages
		MetadataService.InstalledPackage installedPackageA = new MetadataService.InstalledPackage();
		installedPackageA.fullName = 'packagea';
		MetadataService.InstalledPackage installedPackageB = new MetadataService.InstalledPackage();
		installedPackageB.fullName = 'packageb';
		MetadataService.AsyncResult[] results = createService().deleteMetadata(
		    new List<MetadataService.Metadata> { installedPackageA, installedPackageB });

As described in the Metadata API for Apex docs you need to handle the AsyncResult’s via VF actionPoller or Batch Apex. For Batch Apex, replace the last line of the install sample with the following to process the installation API calls in batch and have the job email you the results.

		MetadataCreateJob.run(
			new List<MetadataCreateJob.Item> { 
				new MetadataCreateJob.Item(installedPackageA ),
				new MetadataCreateJob.Item(installedPackageB ) },
			new MetadataCreateJob.EmailNotificationMetadataAsyncCallback());				

Possibilities!

For me the above is a really exciting possibility, you could for example develop a VF page as part of your core package that allows administrators to see other extension packages available with your package and install them directly! Now lets wait to see when the ability to API drive the packaging process arrives, in the meantime enjoy!