Ruby gem for interacting with the Salesforce Metadata API.
Clone or download
Pull request Compare This branch is 4 commits ahead, 183 commits behind ejholmes:master.
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.

Metaforce travis-ci

Metaforce is a Ruby gem for interacting with the Salesforce Metadata API. The goal of this project is to make the Migration Tool obsolete, favoring Rake over Ant.



gem install metaforce


client = :username => 'username',
    :password => 'password',
    :security_token => 'security token')

# Describe the metadata on the organization
# => [{ :child_xml_names => "CustomLabel", :directory_name => "labels" ... }]

# List all custom objects
# => [{ :created_by_id => "005U0000000EGpcIAG", :created_by_name => "Eric Holmes", ... }]

# Deploy metadata to the organization
deployment = client.deploy(File.expand_path('path/to/src'))
# => #<Metaforce::Transaction:0x00000102779bf8 @id="04sU0000000WNWoIAO" @type=:deploy> 

# Get the result
# => { :id => "04sU0000000WNWoIAO", :messages => [{ :changed => true ... :success => true }

# Retrieve the metadata components specified in package.xml and unzip to the "retrieved" directory

# Create a Visualforce page
client.create_apex_page(:full_name => 'TestPage', :label => 'TestPage')

# Update a Visualforce page
client.update_apex_page('OldName', :full_name => 'NewName')

# Delete a Visualforce page


This gem is far from being feature complete. Here's a list of things that still need to be done.

  • Implement command line utility that can watch the directory and deploy when a file changes.
  • Implement some helper methods for diffing metadata.
  • Ability to deploy directly from a git repository.
  • And some other stuff that I haven't quite thought of yet...


If you'd like to contribute code, please fork the repository and implement your feature on a new branch, then send me a pull request with a detailed description. Please provide applicable rspec specs.

Version History

0.5.3 (June 8, 2012)

  • Only trigger reauthentication if the response contains INVALID_SESSION_ID.

0.5.2 (June 8, 2012)

  • The services client now reauthentications on Savon::SOAP::Fault.


  • Add thor integration.

0.5.0 (March 23, 2012)

  • Implemented CRUD calls.

0.4.1 (March 8, 2012)

  • Bug fixes

0.4.0 (March 2, 2012)

  • Various bug fixes and improvements.
  • Removed DSL to focus on core functionality.

0.3.5 (February 11, 2012)

  • Allow rake tasks to get credentials from a metaforce.yml file.

0.3.4 (February 9, 2012)

  • Add rake tasks.

0.3.3 (February 9, 2012)

  • Added a logger for logging requests.
  • Allow api version to be set when calling Metaforce::Metadata::Client.describe.

0.3.2 (February 3, 2012)

  • Improved documentation.
  • Added .status method to Transaction class.

0.3.1 (February 3, 2012)

  • Dynamically defined helper methods for .list (e.g. client.list_apex_class, client.list_custom_object).
  • The Metaforce::Metadata::Client.describe method now caches the results to minimize latency. describe! can be used to force a refresh.

0.3.0.alpha (January 29, 2012)

  • Ability to retrieve metadata from an organization.
  • Added a DSL.

0.2.0.alpha (January 28, 2012)

  • Gem now supports interacting with the metadata api.

0.1.0.alpha (January 10, 2012)

  • Ability to parse and modify package.xml files easily.


Copyright (C) 2012 Eric Holmes

This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.