Scripting the Apex Metadata API and Batch Apex Support

The Apex Metadata API (a native Apex wrapper around the Salesforce equivalent) has had a steady increase of followers and questions since it was created in October 2012. Judging by the feedback I have had its enabling quite a few time saving and wizard style solutions in your native applications! This blog introduces a new example using Batch Apex to ‘script’ the creation of custom objects, fields, pages etc. in an org more easily in a none UI context.

The Salesforce Metadata API is an asynchronous API, which means you have to poll it to determine the fate of your requests. At launch I provided some examples of doing this via apex:actionPoller using Visualforce. Recently given some queries on the forums and this blog, I decided to invest a little more in a Batch Apex example. The new MetadataCreateJob class (and test) implements Batch Apex using a custom iterator to process the Metadata items in order and will even wait for proceeding items to complete, to handle dependencies.

The following example (included here in the repo) will perform the following steps with the given name.

1. Create a custom object of the given name
2. Create 2 custom fields on the object
3. Create a Visualforce page that references the two fields using the standard controller
4. Email the user once the above is completed, including any errors returned by checkStatus.

Trying out the sample code…

If you want to try out the following example install, MetadataService.cls, MetadataServiceExamples.cls and MetadataCreateJob.cls in your org (test classes are also available). You will also need to add to your Remote Site Settings (under Security Controls), https://na11.salesforce.com (changing na11 to your org instance). Then issue the following command from the Developer Console or Execute Annoynmous from Eclipse.

MetadataServiceExamples.dynamicCreation('Test');

Once you receive the confirmation email, you will then see the following items in your org…

If you repeat the above you should see the following errors (returned from Metadata API’s checkStatus operation) in the email once the job is complete.

The code to perform the above steps is shown below, note how the ‘wait’ parameter is used on the job items to cause the items to be processed only once a dependent proceeding item has been completed.

	public static void dynamicCreation(String objectName)
	{
		// Define Metadata item to create a Custom Object
		MetadataService.CustomObject customObject = new MetadataService.CustomObject();
		customObject.fullName = objectName + '__c';
		customObject.label = objectName;
		customObject.pluralLabel = objectName+'s';
		customObject.nameField = new MetadataService.CustomField();
		customObject.nameField.type_x = 'Text';
		customObject.nameField.label = 'Test Record';
		customObject.deploymentStatus = 'Deployed';
		customObject.sharingModel = 'ReadWrite';

		// Define Metadata item to create a Custom Field on the above object
		MetadataService.CustomField customField1 = new MetadataService.CustomField();
		customField1.fullName = objectName+'__c.TestField1__c';
		customField1.label = 'Test Field 1';
		customField1.type_x = 'Text';
		customField1.length = 42;

		// Define Metadata item to create a Custom Field on the above object
		MetadataService.CustomField customField2 = new MetadataService.CustomField();
		customField2.fullName = objectName+'__c.TestField2__c';
		customField2.label = 'Test Field 2';
		customField2.type_x = 'Text';
		customField2.length = 42;

		// Define Metadata item to create a Visualforce page to display the above field
		MetadataService.ApexPage apexPage = new MetadataService.ApexPage();
		apexPage.apiVersion = 25;
		apexPage.fullName = objectName.toLowercase();
		apexPage.label = objectName + ' Page';
		apexPage.content = EncodingUtil.base64Encode(Blob.valueOf(
			'<apex:page standardController=\''+objectName+'__c\'>'+
				'{!' + objectName + '__c.TestField1__c}' +
				'{!' + objectName + '__c.TestField2__c}' +
			'</apex:page>'));

		// Pass the Metadata items to the job for processing, indicating any dependencies
		MetadataCreateJob.run(
			new List<MetadataCreateJob.Item> {
					new MetadataCreateJob.Item(customObject),
					new MetadataCreateJob.Item(customField1, null, true), // Set wait to true, to process after object creation
					new MetadataCreateJob.Item(customField2),
					new MetadataCreateJob.Item(apexPage, null, true) // Set wait to true, to process after field creation
				},
			new MetadataCreateJob.EmailNotificationMetadataAsyncCallback());
	}

Note: This will email the user when the work is completed. However you can implement your own callback handler if you wish, take a look at the MetadataCreateJob.IMetadataAsyncCallback interface and the email example included.

This is quite a basic example, but starts to illustrate how you could build a more dynamic solution. Perhaps one that takes some form of data input, like a CSV file, which will create the object and fields, before importing the data. Or one that is fired from an Apex Trigger whenever some configuration data in your application is changed?

What will you do with this?