Metaforce

Metaforce is a Ruby gem for interacting with the Salesforce Metadata and Services APIs.

Installation

Add this line to your application's Gemfile:

gem 'metaforce'

And then execute:

$ bundle

Or install it yourself as:

$ gem install metaforce

Usage

Initialization

Username and Password

To initialize a new client, you call Metaforce.new with a hash that specifies the :username, :password, and :security_token.

client = Metaforce.new :username => 'username',
  :password => 'password',
  :security_token => 'security token'

Or you can specify the username, password and security token with environment variables:

export SALESFORCE_USERNAME="username"
export SALESFORCE_PASSWORD="password"
export SALESFORCE_SECURITY_TOKEN="security token"

client = Metaforce.new

Asynchronous Tasks

Some calls to the SOAP API's are performed asynchronously (such as deployments), meaning the response needs to be polled for. Any call to the SOAP API's that are performed asynchronously will return a Metaforce::Job object, which can be used to subscribe to on_complete and on_error callbacks. The Metaforce::Job class will poll the status of the asynchronous job in a thread until it completes or fails.

deploy(path, options={})

Takes a path (can be a path to a directory, or a zip file), and a set of DeployOptions and returns a Metaforce::Job::Deploy.

client.deploy(File.expand_path('./src'))
  .on_complete { |job| puts "Finished deploy #{job.id}!" }
  .on_error    { |job| puts "Something bad happened!" }
  .perform
#=> #<Metaforce::Job::Deploy @id='1234'>

retrieve_unpackaged(manifest, options={})

Takes a manifest (Metaforce::Manifest or a path to a package.xml file) and a set of RetrieveOptions and returns a Metaforce::Job::Retrieve.

manifest = Metaforce::Manifest.new(:custom_object => ['Account'])
client.retrieve_unpackaged(manifest)
  .extract_to('./tmp')
  .perform
#=> #<Metaforce::Job::Retrieve @id='1234'>

create(type, metadata={})

Takes a Symbol type and a Hash of Metadata Attributes and returns a Metaforce::Job::CRUD.

client.create(:apex_page, full_name: 'Foobar', content: 'Hello World!')
  .on_complete { |job| puts "ApexPage created." }
  .perform
#=> #<Metaforce::Job::CRUD @id='1234'>

update(type, current_name metadata={})

Takes a Symbol type, the current full_name of the resource, and a Hash of Metadata Attributes and returns a Metaforce::Job::CRUD.

client.update(:apex_page, 'Foobar', content: 'Hello World! Some new content!')
  .on_complete { |job| puts "ApexPage updated." }
  .perform
#=> #<Metaforce::Job::CRUD @id='1234'>

delete(type, *args)

Takes a Symbol type, and the full_name of a resource and returns a Metaforce::Job::CRUD.

client.delete(:apex_page, 'Foobar')
  .on_complete { |job| puts "ApexPage deleted." }
  .perform
#=> #<Metaforce::Job::CRUD @id='1234'>

send_email(options={})

Sends a SingleEmailMessage using Salesforce.

client.send_email(
  to_addresses: ['foo@bar.com'],
  subject: 'Hello World',
  plain_text_body: 'Hello World'
)

If you're using Rails, check out the metaforce-delivery_method gem, which allows you to use Salesforce as the delivery mechanism for sending emails.

Command-line

Metaforce also comes with a handy command line utility that can deploy and retrieve code from Salesforce. It also allows you to watch a directory and deploy when anything changes.

When you deploy, it will also run all tests and provide you with a report, similar to rspec.

$ metaforce deploy ./src
Deploying: ./src

$ metaforce watch ./src
Watching: ./src

$ metaforce retrieve ./src
Retrieving: ./src/package.xml

$ metaforce retrieve ./src/package.xml ./other-location
Retrieving: ./src/package.xml

.metaforce.yml

The metaforce command will pull it's configuration from a .metaforce.yml file, if present. You can provide options for multiple environments, then use the -e swtich on the command line to use an environment. See the examples directory for an example.

Contributing

Fork it
Create your feature branch (git checkout -b my-new-feature)
Commit your changes (git commit -am 'Added some feature')
Push to the branch (git push origin my-new-feature)
Create new Pull Request

mhui/metaforce