metaforce 0.2.0.alpha

data/.gitignore

@@ -0,0 +1,7 @@
+*.gem
+.bundle
+Gemfile.lock
+pkg/*
+deploy.zip
+retrieve.zip
+test.rb

data/.rvmrc

@@ -0,0 +1,55 @@
+#!/usr/bin/env bash
+
+# This is an RVM Project .rvmrc file, used to automatically load the ruby
+# development environment upon cd'ing into the directory
+
+# First we specify our desired <ruby>[@<gemset>], the @gemset name is optional.
+environment_id="ruby-1.9.2-p290@metaforce"
+
+#
+# Uncomment following line if you want options to be set only for given project.
+#
+# PROJECT_JRUBY_OPTS=( --1.9 )
+
+#
+# First we attempt to load the desired environment directly from the environment
+# file. This is very fast and efficient compared to running through the entire
+# CLI and selector. If you want feedback on which environment was used then
+# insert the word 'use' after --create as this triggers verbose mode.
+#
+if [[ -d "${rvm_path:-$HOME/.rvm}/environments" \
+  && -s "${rvm_path:-$HOME/.rvm}/environments/$environment_id" ]]
+then
+  \. "${rvm_path:-$HOME/.rvm}/environments/$environment_id"
+
+  if [[ -s "${rvm_path:-$HOME/.rvm}/hooks/after_use" ]]
+  then
+    . "${rvm_path:-$HOME/.rvm}/hooks/after_use"
+  fi
+else
+  # If the environment file has not yet been created, use the RVM CLI to select.
+  if ! rvm --create  "$environment_id"
+  then
+    echo "Failed to create RVM environment '${environment_id}'."
+    return 1
+  fi
+fi
+
+#
+# If you use an RVM gemset file to install a list of gems (*.gems), you can have
+# it be automatically loaded. Uncomment the following and adjust the filename if
+# necessary.
+#
+# filename=".gems"
+# if [[ -s "$filename" ]]
+# then
+#   rvm gemset import "$filename" | grep -v already | grep -v listed | grep -v complete | sed '/^$/d'
+# fi
+
+# If you use bundler, this might be useful to you:
+# if command -v bundle && [[ -s Gemfile ]]
+# then
+#   bundle install
+# fi
+
+

data/Gemfile

@@ -0,0 +1,10 @@
+source "http://rubygems.org"
+
+# Specify your gem's dependencies in metaforce.gemspec
+gemspec
+
+group :development do
+  gem "guard"
+  gem "guard-rspec"
+  gem "growl"
+end

data/Guardfile

@@ -0,0 +1,9 @@
+# A sample Guardfile
+# More info at https://github.com/guard/guard#readme
+
+group :specs do
+  guard :rspec do
+    watch(%r{^spec/.+_spec\.rb$})
+    watch(%r{^lib/metaforce/(.+)\.rb$}) { |m| "spec/lib/#{m[1]}_spec.rb" }
+  end
+end

data/README.md

@@ -0,0 +1,59 @@
+# Metaforce
+Metaforce is a Ruby gem for interacting with the [Salesforce Metadata API](http://www.salesforce.com/us/developer/docs/api_meta/index.htm).
+The goal of this project is to make the [Migration Tool](http://www.salesforce.com/us/developer/docs/apexcode/Content/apex_deploying_ant.htm) obsolete, favoring Rake over Ant.
+
+Metaforce is in active development and is currently in alpha status. Don't use
+it to deploy code to production instances. You've been warned!
+
+## Installation
+```bash
+gem install metaforce -v '0.2.0.alpha'
+```
+
+## Usage
+``` ruby
+client = Metaforce::Metadata::Client.new :username => 'username',
+    :password => 'password',
+    :security_token => 'security token')
+
+client.describe
+# => { :metadata_objects => [{ :child_xml_names => "CustomLabel", :directory_name => "labels" ... }
+
+client.list(:type => "CustomObject")
+# => [{ :created_by_id => "005U0000000EGpcIAG", :created_by_name => "Eric Holmes", ... }]
+
+deployment = client.deploy(File.expand_path("../src"))
+# => #<Metaforce::Transaction:0x00000102779bf8 @id="04sU0000000WNWoIAO" @type=:deploy> 
+
+deployment.done?
+# => false
+
+deployment.result(:wait_until_done => true)
+# => { :id => "04sU0000000WNWoIAO", :messages => [{ :changed => true ... :success => true }
+```
+
+## Roadmap
+This gem is far from being feature complete. Here's a list of things that still
+need to be done.
+
+* Implement .retrieve for retrieving metadata.
+* Implement CRUD based calls <http://www.salesforce.com/us/developer/docs/api_meta/Content/meta_crud_based_calls_intro.htm>.
+* Implement some helper methods for diffing metadata.
+* And some other stuff that I haven't quite thought of yet...
+
+## License
+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.

data/Rakefile

@@ -0,0 +1,6 @@
+require "bundler/gem_tasks"
+
+desc "Start an irb session"
+task :console do
+  sh "irb -I lib -r metaforce"
+end

data/lib/metaforce.rb

@@ -0,0 +1,4 @@
+require 'metaforce/version'
+require 'metaforce/config'
+require 'metaforce/manifest'
+require 'metaforce/api'

data/lib/metaforce/api.rb

@@ -0,0 +1,3 @@
+require 'metaforce/api/services'
+require 'metaforce/api/metadata'
+require 'metaforce/api/transaction'

data/lib/metaforce/api/metadata.rb

@@ -0,0 +1,117 @@
+require 'metaforce/manifest'
+require 'savon'
+require 'zip/zip'
+require 'base64'
+require 'ostruct'
+
+module Metaforce
+  module Metadata
+    class Client
+      DEPLOY_ZIP = 'deploy.zip'
+      RETRIEVE_ZIP = 'retrieve.zip'
+
+      def initialize(options=nil)
+        @session = Services::Client.new(options).session
+        @client = Savon::Client.new File.expand_path("../../../../wsdl/#{Metaforce.configuration.api_version}/metadata.xml", __FILE__) do |wsdl|
+          wsdl.endpoint = @session[:metadata_server_url]
+        end
+        @header = {
+            "ins0:SessionHeader" => {
+              "ins0:sessionId" => @session[:session_id]
+            }
+        }
+      end
+
+      # Specify an array of component types to list
+      #
+      # example:
+      # [
+      #   { :type => "ApexClass" },
+      #   { :type => "ApexComponent" }
+      # ]
+      def list(queries=[])
+        unless queries.is_a?(Array)
+          queries = [ queries ]
+        end
+        response = @client.request(:list_metadata) do |soap|
+          soap.header = @header
+          soap.body = {
+            :queries => queries
+          }
+        end
+        response.body[:list_metadata_response][:result]
+      end
+
+      # Describe the organization's metadata
+      def describe
+        response = @client.request(:describe_metadata) do |soap|
+          soap.header = @header
+        end
+        response.body[:describe_metadata_response][:result]
+      end
+
+      # Checks the status of an async result
+      #
+      # If type is :retrieve or :deploy, it returns the RetrieveResult or
+      # DeployResult, respectively
+      def status(ids, type=nil)
+        request = "check_status"
+        request = "check_#{type.to_s}_status" unless type.nil?
+        ids = [ ids ] unless ids.is_a?(Array)
+
+        response = @client.request(request.to_sym) do |soap|
+          soap.header = @header
+          soap.body = {
+            :ids => ids
+          }
+        end
+        response.body["#{request}_response".to_sym][:result]
+      end
+
+      # Returns true if the deployment with id id is done, false otherwise
+      def done?(id)
+        self.status(id)[:done]
+      end
+
+      # Deploys dir to the organisation
+      def deploy(dir, options={})
+        options = OpenStruct.new options
+
+        if dir.is_a?(String)
+          filename = File.join(File.dirname(dir), DEPLOY_ZIP)
+          zip_contents = create_deploy_file(filename, dir)
+        elsif dir.is_a?(File)
+          zip_contents = Base64.encode64(dir.read)
+        end
+
+        yield options if block_given?
+
+        response = @client.request(:deploy) do |soap|
+          soap.header = @header
+          soap.body = {
+            :zip_file => zip_contents,
+            :deploy_options => options.marshal_dump
+          }
+        end
+        Transaction.deployment self, response[:deploy_response][:result][:id]
+      end
+
+    private
+    
+      # Creates the deploy file, reads in the contents and returns the base64
+      # encoded data
+      def create_deploy_file(filename, dir)
+        File.delete(filename) if File.exists?(filename)
+        Zip::ZipFile.open(filename, Zip::ZipFile::CREATE) do |zip|
+          Dir["#{dir}/**/**"].each do |file|
+            zip.add(file.sub(dir + '/', ''), file)
+          end
+        end
+        contents = Base64.encode64(File.open(filename, "rb").read)
+        File.delete(filename)
+        contents
+      end
+
+    end
+  end
+end

data/lib/metaforce/api/services.rb

@@ -0,0 +1,33 @@
+require 'savon'
+
+module Metaforce
+  module Services
+    class Client
+      attr_reader :session
+
+      def initialize(options=nil)
+        options = {
+          :username => Metaforce.configuration.username,
+          :password => Metaforce.configuration.password,
+          :security_token => Metaforce.configuration.security_token
+        } if options.nil?
+        @session = self.login(options[:username], options[:password], options[:security_token])
+      end
+
+      def login(username, password, security_token=nil)
+        password = "#{password}#{security_token}" unless security_token.nil?
+        client = Savon::Client.new File.expand_path("../../../../wsdl/#{Metaforce.configuration.api_version}/partner.xml", __FILE__) do |wsdl|
+          wsdl.endpoint = wsdl.endpoint.to_s.sub(/login/, 'test') if Metaforce.configuration.test
+        end
+        response = client.request(:login) do
+          soap.body = {
+            :username => username,
+            :password => password
+          }
+        end
+        { :session_id => response.body[:login_response][:result][:session_id],
+          :metadata_server_url =>  response.body[:login_response][:result][:metadata_server_url] }
+      end
+    end
+  end
+end

data/lib/metaforce/api/transaction.rb

@@ -0,0 +1,53 @@
+module Metaforce
+
+  # Convenience class for deployment/retrieval results
+  class Transaction
+    attr_reader :id
+    attr_reader :type
+
+    def initialize(client, id, type)
+      @id = id
+      @client = client
+      @type = type
+    end
+
+    def self.deployment(client, id)
+      self.new client, id, :deploy
+    end
+
+    def self.retrieval(client, id)
+      self.new client, id, :retrieve
+    end
+
+    # Returns true if the transaction has completed, false otherwise
+    def done?
+      @done = @client.done?(@id) unless @done
+      @done
+    end
+    alias :complete? :done?
+    alias :completed? :done?
+    
+    # Returns the deploy or retrieve result
+    def result(options={})
+      self.wait_until_done if options[:wait_until_done]
+      raise "Request is not complete! Be sure to call .done? first!" unless @done
+      @result = @client.status(@id, @type) if @result.nil?
+      @result
+    end
+
+    # Enters a loop until .done? returns true
+    def wait_until_done
+      max_wait = 30
+      wait_time = 1
+      until self.done?
+        sleep(wait_time)
+        if wait_time < 30
+          wait_time *= 2
+        else
+          wait_time = max_wait
+        end
+      end
+    end
+
+  end
+end

data/lib/metaforce/config.rb

@@ -0,0 +1,24 @@
+module Metaforce
+  class << self
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    def configure
+      yield configuration
+    end
+  end
+
+  class Configuration
+    attr_accessor :api_version
+    attr_accessor :username
+    attr_accessor :password
+    attr_accessor :security_token
+    attr_accessor :test
+
+    def initialize
+      @api_version = "23.0"
+      @test = false
+    end
+  end
+end

data/lib/metaforce/manifest.rb

@@ -0,0 +1,313 @@
+require 'nokogiri'
+
+module Metaforce
+  class Manifest
+    SFDC_API_VERSION = "23.0"
+
+    # example format
+    # {
+    #   :apex_class => [
+    #     "TestController",
+    #     "TestClass"
+    #   ],
+    #   :apex_component => [
+    #     "SiteLogin"
+    #   ]
+    # }
+    def initialize(components={})
+      # Map component type => folder
+      if components.is_a?(Hash)
+        @components = components
+      elsif components.is_a?(String)
+        @components = {}
+        self.parse(components)
+      end
+    end
+
+    # Adds components to the package
+    def add(type, members=nil)
+      unless members.nil?
+        @components[type] = [] if @components[type].nil?
+        members = [members] if members.is_a?(String)
+        members.each do |member|
+          member = member.gsub(/.*\//, '').gsub(/\..*/, '');
+          @components[type].push(member)
+        end
+      end
+      self
+    end
+
+    # Removes components from the package
+    def remove(type, members=nil)
+      unless members.nil?
+        members = [members] if members.is_a?(String)
+        members.each do |member|
+          member = member.gsub(/.*\//, '').gsub(/\..*/, '');
+          @components[type].delete(member)
+        end
+      end
+      if @components[type].empty?
+        @components.delete(type)
+      end
+      self
+    end
+
+    # Filters the components based on a list of files
+    def only(files)
+      components = @components
+      @components = {}
+      files.each do |file|
+        parts = file.split('/').last(2)
+        folder = parts[0]
+        file = parts[1].gsub(/.*\//, '').gsub(/\..*/, '')
+        components.each_key do |type|
+          if component_folder(type) =~ /#{folder}/i
+            unless components[type].index(file).nil?
+              self.add(type, file);
+            end
+          end
+        end
+      end
+      self
+    end
+
+    # Returns the components name
+    def component_name(key)
+      COMPONENT_TYPE_MAP[key][:name]
+    end
+
+    # Returns the components folder
+    def component_folder(key)
+      COMPONENT_TYPE_MAP[key][:folder]
+    end
+
+    # Returns a key for the component name
+    def component_key(name)
+      COMPONENT_TYPE_MAP.each do |key, component|
+        return key if component[:name] == name
+      end
+    end
+
+    # Returns a string containing a package.xml file
+    def to_xml
+      xml_builder = Nokogiri::XML::Builder.new do |xml|
+        xml.Package("xmlns" => "http://soap.sforce.com/2006/04/metadata") {
+          @components.each do |key, members|
+            xml.types {
+              members.each do |member|
+                xml.members member
+              end
+              xml.name component_name(key)
+            }
+          end
+          xml.version SFDC_API_VERSION
+        }
+      end
+      xml_builder.to_xml
+    end
+
+    def to_hash
+      @components
+    end
+
+    def to_package
+      components = []
+      @components.each do |type, members|
+        name = component_name(type)
+        components.push({
+          :members => members,
+          :name => name
+        })
+      end
+      components
+    end
+
+    # Parses a package.xml file
+    def parse(file)
+      document = Nokogiri::XML(file).remove_namespaces!
+      document.xpath('//types').each do |type|
+        name = type.xpath('name').first.content
+        key = component_key(name);
+        type.xpath('members').each do |member|
+          if @components[key].is_a?(Array)
+            @components[key].push(member.content)
+          else
+            @components[key] = [member.content]
+          end
+        end
+      end
+      self
+    end
+
+    COMPONENT_TYPE_MAP = {
+      :action_override => {
+        :name => "ActionOverride",
+        :folder => "objects"
+      },
+      :analytics_snapshot => {
+        :name => "AnalyticsSnapshot",
+        :folder => "analyticsnapshots"
+      },
+      :apex_class => {
+        :name => "ApexClass",
+        :folder => "classes"
+      },
+      :article_type => {
+        :name => "ArticleType",
+        :folder => "objects"
+      },
+      :apex_component => {
+        :name => "ApexComponent",
+        :folder => "components"
+      },
+      :apex_page => {
+        :name => "ApexPage",
+        :folder => "pages"
+      },
+      :apex_trigger => {
+        :name => "ApexTrigger",
+        :folder => "triggers"
+      },
+      :business_process => {
+        :name => "BusinessProcess",
+        :folder => "objects"
+      },
+      :custom_application => {
+        :name => "CustomApplication",
+        :folder => "applications"
+      },
+      :custom_field => {
+        :name => "CustomField",
+        :folder => "objects"
+      },
+      :custom_labels => {
+        :name => "CustomLabels",
+        :folder => "labels"
+      },
+      :custom_object => {
+        :name => "CustomObject",
+        :folder => "objects"
+      },
+      :custom_object_translation => {
+        :name => "CustomObjectTranslation",
+        :folder => "objectTranslations"
+      },
+      :custom_page_web_link => {
+        :name => "CustomPageWebLink",
+        :folder => "weblinks"
+      },
+      :custom_site => {
+        :name => "CustomSite",
+        :folder => "sites"
+      },
+      :custom_tab => {
+        :name => "CustomTab",
+        :folder => "tabs"
+      },
+      :dashboard => {
+        :name => "Dashboard",
+        :folder => "dashboards"
+      },
+      :data_category_group => {
+        :name => "DataCategoryGroup",
+        :folder => "datacategorygroups"
+      },
+      :document => {
+        :name => "Document",
+        :folder => "document"
+      },
+      :email_template => {
+        :name => "EmailTemplate",
+        :folder => "email"
+      },
+      :entitlement_template => {
+        :name => "EntitlementTemplate",
+        :folder => "entitlementTemplates"
+      },
+      :field_set => {
+        :name => "FieldSet",
+        :folder => "objects"
+      },
+      :home_page_component => {
+        :name => "HomePageComponent",
+        :folder => "homePageComponents"
+      },
+      :layout => {
+        :name => "Layout",
+        :folder => "layouts"
+      },
+      :letterhead => {
+        :name => "Letterhead",
+        :folder => "letterhead"
+      },
+      :list_view => {
+        :name => "ListView",
+        :folder => "objects"
+      },
+      :named_filter => {
+        :name => "NamedFilter",
+        :folder => "objects"
+      },
+      :permission_set => {
+        :name => "PermissionSet",
+        :folder => "permissionsets"
+      },
+      :portal => {
+        :name => "Portal",
+        :folder => "portals"
+      },
+      :profile => {
+        :name => "Profile",
+        :folder => "profiles"
+      },
+      :record_type => {
+        :name => "RecordType",
+        :folder => "objects"
+      },
+      :remote_site_setting => {
+        :name => "RemoteSiteSetting",
+        :folder => "remoteSiteSettings"
+      },
+      :report => {
+        :name => "Report",
+        :folder => "reports"
+      },
+      :report_type => {
+        :name => "ReportType",
+        :folder => "reportTypes"
+      },
+      :scontroler => {
+        :name => "Scontroler",
+        :folder => "scontrols"
+      },
+      :sharing_reason => {
+        :name => "SharingReason",
+        :folder => "objects"
+      },
+      :sharing_recalculation => {
+        :name => "SharingRecalculation",
+        :folder => "objects"
+      },
+      :static_resource => {
+        :name => "StaticResource",
+        :folder => "staticResources"
+      },
+      :translations => {
+        :name => "Translations",
+        :folder => "translations"
+      },
+      :validation_rule => {
+        :name => "ValidationRule",
+        :folder => "objects"
+      },
+      :weblink => {
+        :name => "Weblink",
+        :folder => "objects"
+      },
+      :workflow => {
+        :name => "Workflow",
+        :folder => "workflows"
+      }
+    }
+  end
+end