rightsignature 0.1.0

data/lib/rightsignature/connection/oauth_connection.rb

@@ -0,0 +1,34 @@
+module RightSignature
+  class OauthConnection
+
+    class << self
+      def oauth_consumer
+        @oauth_consumer ||= OAuth::Consumer.new(
+          RightSignature::configuration[:consumer_key],
+          RightSignature::configuration[:consumer_secret],
+          {
+           :site              => "https://rightsignature.com",
+           :scheme            => :header,
+           :http_method        => :post,
+           :authorize_path    =>'/oauth/authorize', 
+           :access_token_path =>'/oauth/access_token', 
+           :request_token_path=>'/oauth/request_token'
+          }
+        )
+      end
+      
+      def access_token
+        @access_token ||= OAuth::AccessToken.new(oauth_consumer,  RightSignature::configuration[:access_token],  RightSignature::configuration[:access_secret])
+      end
+      
+      def request(method, *options)
+        options.last ||= {}
+        options.last["Accept"] ||= "*/*"
+        options.last["content-type"] ||= "application/xml"
+
+        self.access_token.__send__(method, *options)
+      end
+    end
+
+  end
+end

data/lib/rightsignature/connection/token_connection.rb

@@ -0,0 +1,19 @@
+module RightSignature
+  class TokenConnection
+    include HTTParty
+    base_uri 'https://rightsignature.com'
+    format :xml
+
+    class <<self
+      def request(method, url, options)
+        options[:headers] ||= {}
+        options[:headers]['api-token'] = RightSignature::configuration[:api_token]
+        options[:headers]["Accept"] ||= "*/*"
+        options[:headers]["content-type"] ||= "application/xml"
+        __send__(method, url, options)
+      end
+      
+    end
+
+  end
+end

data/lib/rightsignature/document.rb

@@ -0,0 +1,216 @@
+module RightSignature
+  class Document
+    extend RightSignature::Helpers
+
+    class << self
+      
+      def list(options={})
+        options[:tags] = TagsHelper.mixed_array_to_string_array(options[:tags]) if options[:tags]
+        options[:state] = options[:state].join(',') if options[:state] && options[:state].is_a?(Array)
+        RightSignature::Connection.get "/api/documents.xml", options
+      end
+      
+      def details(guid)
+        RightSignature::Connection.get "/api/documents/#{guid}.xml"
+      end
+      
+      def batch_details(guids)
+        RightSignature::Connection.get "/api/documents/#{guids.join(',')}/batch_details.xml"
+      end
+      
+      def send_reminder(guid)
+        RightSignature::Connection.post "/api/documents/#{guid}/send_reminders.xml", {}
+      end
+      
+      def trash(guid)
+        RightSignature::Connection.post "/api/documents/#{guid}/trash.xml", {}
+      end
+
+      def extend_expiration(guid)
+        RightSignature::Connection.post "/api/documents/#{guid}/extend_expiration.xml", {}
+      end
+      
+      # This will REPLACE the tags on a document
+      # tags are an array of 'tag_name' or {'tag_name' => 'value'}
+      # Hash style:
+      # {:name => value}
+      def update_tags(guid, tags)
+        RightSignature::Connection.post "/api/documents/#{guid}/update_tags.xml", { :tags => TagsHelper.array_to_xml_hash(tags) }
+      end
+      
+      # Creates a document from a raw data
+      # * file: file binary. Ex. File.read('myfile.pdf')
+      # * filename: original filename
+      # * subject: subject of the document that'll appear in email
+      # * recipients: Recipients of the document, should be an array of hashes with :name, :email, and :role ('cc' or 'signer'). 
+      #     An optional :is_sender (true/false) is used to referrence the API User and won't need to supply :name and :email
+      #     Ex. CC to support@rightsignature.com, with sender and john@rightsignature.com as a signer
+      #     [
+      #       {:name => "RightSignature", :email => "support@rightsignature.com", :role => 'cc'},
+      #       {:name => "John Bellingham", :email => "john@rightsignature.com", :role => 'signer'},
+      #       {'is_sender' => true, :role => 'signer'},
+      #     ]
+      # * options: other optional values
+      #     - description: document description that'll appear in the email
+      #     - action: 'send' or 'redirect'. Redirect will return a token that will allow another person to send the document under API user's account
+      #     - expires_in: number of days before expiring the document. API only allows 2,5,15, or 30.
+      #     - tags: document tags, an array of string or hashes 'single_tag' (for simple tag) or {'tag_name' => 'tag_value'} (for tuples pairs)
+      #         Ex. ['sent_from_api', {"user_id" => "32"}]
+      #     - callback_url: A URI encoded URL that specifies the location for API to POST a callback notification to when the document has been created and signed. 
+      #         Ex. "http://yoursite/callback"
+      #     - use_text_tags: Document has special Text Tags that RightSignature parse. true or false.
+      #         More info: https://rightsignature.com/apidocs/text_tags
+      def send_document_from_data(file_data, filename, subject, recipients, options={})
+        send_document(subject, recipients, {:type => "base64", :filename => filename, :value => Base64::encode64(file_data)}, options)
+      end
+      
+      # Creates a document from a File or path to file
+      # * file: Path to file or File object
+      # * subject: subject of the document that'll appear in email
+      # * recipients: Recipients of the document, should be an array of hashes with :name, :email, and :role ('cc' or 'signer'). 
+      #     An optional :is_sender (true/false) is used to referrence the API User and won't need to supply :name and :email
+      #     Ex. CC to support@rightsignature.com, with sender and john@rightsignature.com as a signer
+      #     [
+      #       {:name => "RightSignature", :email => "support@rightsignature.com", :role => 'cc'},
+      #       {:name => "John Bellingham", :email => "john@rightsignature.com", :role => 'signer'},
+      #       {'is_sender' => true, :role => 'signer'},
+      #     ]
+      # * options: other optional values
+      #     - description: document description that'll appear in the email
+      #     - action: 'send' or 'redirect'. Redirect will return a token that will allow another person to send the document under API user's account
+      #     - expires_in: number of days before expiring the document. API only allows 2,5,15, or 30.
+      #     - tags: document tags, an array of string or hashes 'single_tag' (for simple tag) or {'tag_name' => 'tag_value'} (for tuples pairs)
+      #         Ex. ['sent_from_api', {"user_id" => "32"}]
+      #     - callback_url: A URI encoded URL that specifies the location for API to POST a callback notification to when the document has been created and signed. 
+      #         Ex. "http://yoursite/callback"
+      #     - use_text_tags: Document has special Text Tags that RightSignature parse. true or false.
+      #         More info: https://rightsignature.com/apidocs/text_tags
+      def send_document_from_file(file, subject, recipients, options={})
+        send_document(subject, recipients, {:type => "base64", :filename => File.basename(file), :value => Base64::encode64(File.read(file)) }, options)
+      end
+      
+      # Creates a document from URL
+      # * url: URL to file
+      # * subject: subject of the document that'll appear in email
+      # * recipients: Recipients of the document, should be an array of hashes with :name, :email, and :role ('cc' or 'signer'). 
+      #     An optional :is_sender (true/false) is used to referrence the API User and won't need to supply :name and :email
+      #     Ex. CC to support@rightsignature.com, with sender and john@rightsignature.com as a signer
+      #     [
+      #       {:name => "RightSignature", :email => "support@rightsignature.com", :role => 'cc'},
+      #       {:name => "John Bellingham", :email => "john@rightsignature.com", :role => 'signer'},
+      #       {'is_sender' => true, :role => 'signer'},
+      #     ]
+      # * options: other optional values
+      #     - description: document description that'll appear in the email
+      #     - action: 'send' or 'redirect'. Redirect will return a token that will allow another person to send the document under API user's account
+      #     - expires_in: number of days before expiring the document. API only allows 2,5,15, or 30.
+      #     - tags: document tags, an array of string or hashes 'single_tag' (for simple tag) or {'tag_name' => 'tag_value'} (for tuples pairs)
+      #         Ex. ['sent_from_api', {"user_id" => "32"}]
+      #     - callback_url: A URI encoded URL that specifies the location for API to POST a callback notification to when the document has been created and signed. 
+      #         Ex. "http://yoursite/callback"
+      #     - use_text_tags: Document has special Text Tags that RightSignature parse. true or false.
+      #         More info: https://rightsignature.com/apidocs/text_tags
+      def send_document_from_url(url, subject, recipients, options={})
+        send_document(subject, recipients, {:type => "url", :filename => File.basename(url), :value => url }, options)
+      end
+      
+      # Creates a document from a base64 encoded file or publicly available URL
+      # * document_data: hash of document source :type ('base64' or 'url'), :filename to be used, :value of source (url or base64 encoded binary)
+      # * subject: subject of the document that'll appear in email
+      # * recipients: Recipients of the document, should be an array of hashes with :name, :email, and :role ('cc' or 'signer'). 
+      #     An optional :is_sender (true/false) is used to referrence the API User and won't need to supply :name and :email
+      #     Ex. CC to support@rightsignature.com, with sender and john@rightsignature.com as a signer
+      #     [
+      #       {:name => "RightSignature", :email => "support@rightsignature.com", :role => 'cc'},
+      #       {:name => "John Bellingham", :email => "john@rightsignature.com", :role => 'signer'},
+      #       {'is_sender' => true, :role => 'signer'},
+      #     ]
+      # * options: other optional values
+      #     - description: document description that'll appear in the email
+      #     - action: 'send' or 'redirect'. Redirect will return a token that will allow another person to send the document under API user's account
+      #     - expires_in: number of days before expiring the document. API only allows 2,5,15, or 30.
+      #     - tags: document tags, an array of string or hashes 'single_tag' (for simple tag) or {'tag_name' => 'tag_value'} (for tuples pairs)
+      #         Ex. ['sent_from_api', {"user_id" => "32"}]
+      #     - callback_url: A URI encoded URL that specifies the location for API to POST a callback notification to when the document has been created and signed. 
+      #         Ex. "http://yoursite/callback"
+      #     - use_text_tags: Document has special Text Tags that RightSignature parse. true or false.
+      #         More info: https://rightsignature.com/apidocs/text_tags
+      # Ex. 
+      # recipients = [
+      #   {:name => "RightSignature", :email => "support@rightsignature.com", :role => 'cc'},
+      #   {:name => "John Bellingham", :email => "john@rightsignature.com", :role => 'signer'},
+      #   {'is_sender' => true, :role => 'signer'},
+      # ]
+      # document_data = {:type => 'base64', :filename => "originalfile.pdf", :value => Base64.encode64(File.read('myfile.pdf','r'))}
+      # options = {
+      #   :tags => ['sent_from_api', 'user_id' => '12345'],
+      #   :expires_in => '5 days',
+      #   :action => "redirect",
+      #   'callback_location' => "http://example.com/doc_callback",
+      #   'use_text_tags' => false
+      # }
+      # RightSignature::send_document( "My Subject", recipients, document_data, options)
+      # 
+      def send_document(subject, recipients, document_data, options={})
+        document_hash = {:document => {
+          :subject => subject,
+          :action => "send",
+          :document_data => document_data
+        }}
+        
+        document_hash[:document][:recipients] = []
+        recipients.each do |recipient_hash|
+          document_hash[:document][:recipients] << { :recipient => recipient_hash}
+        end
+        
+        document_hash[:document].merge!(options)
+        RightSignature::Connection.post "/api/documents.xml", document_hash
+      end
+      
+      # Prefills a document from a base64 encoded file or publicly available URL and returns a url that allows someone to send as the API User
+      # * document_data: hash of document source :type ('base64' or 'url'), :filename to be used, :value of source (url or base64 encoded binary)
+      # * subject: subject of the document that'll appear in email
+      # * recipients: Recipients of the document, should be an array of hashes with :name, :email, and :role ('cc' or 'signer'). 
+      #     An optional :is_sender (true/false) is used to referrence the API User and won't need to supply :name and :email
+      #     Ex. CC to support@rightsignature.com, with sender and john@rightsignature.com as a signer
+      #     [
+      #       {:name => "RightSignature", :email => "support@rightsignature.com", :role => 'cc'},
+      #       {:name => "John Bellingham", :email => "john@rightsignature.com", :role => 'signer'},
+      #       {'is_sender' => true, :role => 'signer'},
+      #     ]
+      # * options: other optional values
+      #     - description: document description that'll appear in the email
+      #     - action: 'send' or 'redirect'. Redirect will return a token that will allow another person to send the document under API user's account
+      #     - expires_in: number of days before expiring the document. API only allows 2,5,15, or 30.
+      #     - tags: document tags, an array of string or hashes 'single_tag' (for simple tag) or {'tag_name' => 'tag_value'} (for tuples pairs)
+      #         Ex. ['sent_from_api', {"user_id" => "32"}]
+      #     - callback_url: A URI encoded URL that specifies the location for API to POST a callback notification to when the document has been created and signed. 
+      #         Ex. "http://yoursite/callback"
+      #     - use_text_tags: Document has special Text Tags that RightSignature parse. true or false.
+      #         More info: https://rightsignature.com/apidocs/text_tags
+      # Ex. 
+      # recipients = [
+      #   {:name => "RightSignature", :email => "support@rightsignature.com", :role => 'cc'},
+      #   {:name => "John Bellingham", :email => "john@rightsignature.com", :role => 'signer'},
+      #   {'is_sender' => true, :role => 'signer'},
+      # ]
+      # document_data = {:type => 'base64', :filename => "originalfile.pdf", :value => Base64.encode64(File.read('myfile.pdf','r'))}
+      # options = {
+      #   :tags => ['sent_from_api', 'user_id' => '12345'],
+      #   :expires_in => '5 days',
+      #   :action => "redirect",
+      #   'callback_location' => "http://example.com/doc_callback",
+      #   'use_text_tags' => false
+      # }
+      # RightSignature::generate_document_redirect_url( "My Subject", recipients, document_data, options)
+      #
+      def generate_document_redirect_url(subject, recipients, document_data, options={})
+        options[:action] = "redirect"
+        response = send_document(subject, recipients, document_data, options)
+        
+        "#{RightSignature::Connection.site}/builder/new?rt=#{response['document']['redirect_token']}"
+      end
+      
+    end
+  end
+end

data/lib/rightsignature/errors.rb

@@ -0,0 +1,28 @@
+module RightSignature
+  class ResponseError < Exception
+    attr_reader :response
+
+    def initialize(response, message=nil)
+      self.set_backtrace(caller[1..-1]) if self.backtrace.nil?
+      @response = response
+      super((message || @response.message))
+    end
+
+    def code
+      @response.code
+    end
+  
+    def common_solutions
+      if @response.code.to_i == 406
+        "Check the Content-Type and makes sure it's the correct type (usually application/json or application/xml), ensure url has .xml or .json at the end, check 'Accept' header to allow xml or json ('*/*' for anything)"
+      elsif @response.code.to_i  == 401
+        "Check your credentials and make sure they are correct and not expired"
+      elsif @response.code.to_i  >= 500 && @response.code.to_i  < 600
+        "Check the format of your xml or json"
+      end
+    end
+  end
+
+  class TokenResponseError < Exception; end
+  class OAuthResponseError < Exception; end
+end

data/lib/rightsignature/helpers/normalizing.rb

@@ -0,0 +1,79 @@
+module RightSignature::Helpers
+  module TagsHelper
+    class <<self
+      def mixed_array_to_string_array(array_of_tags)
+        return array_of_tags unless array_of_tags.is_a?(Array)
+  
+        tags = []
+        array_of_tags.each_with_index do |tag, idx|
+          if tag.is_a? Hash
+            tags << tag.first.join(':')
+          elsif tag.is_a? String
+            tags << tag
+          else
+            raise "Tags should be an array of Strings ('tag_name') or Hashes ({'tag_name' => 'value'})"
+          end
+        end
+  
+        tags.join(',')
+      end
+  
+      def array_to_xml_hash(tags_array)
+        tags_array.map do |t|
+          if t.is_a? Hash
+            name, value = t.first
+            {:tag => {:name => name, :value => value}}
+          else
+            {:tag => {:name => t}}
+          end
+        end
+      end
+      
+    end
+  end
+  
+  module RolesHelper
+    class <<self
+      # Converts [{"Role Name" => {:name => "John", :email => "email@example.com"}}] to 
+      #   [{:role => {:name => "John", :email => "email@example.com", "@role_name" => "Role Name"} }]
+      def array_to_xml_hash(roles_array)
+        roles_hash_array = []
+        roles_array.each do |role_hash|
+          name, value = role_hash.first
+          raise "Hash '#{role_hash.inspect}' is malformed, should be something like {ROLE_NAME => {:name => \"a\", :email => \"a@a.com\"}}" unless value.is_a? Hash and name.is_a? String
+          roles_hash_array << {:role => value.merge({"@role_name" => name})}
+        end
+      
+        roles_hash_array
+      end
+
+    end
+  end
+
+  
+  module MergeFieldsHelper
+    class <<self
+      # Converts [{"Role Name" => {:name => "John", :email => "email@example.com"}}] to 
+      #   [{"role roles_name=\"Role Name\"" => {:role => {:name => "John", :email => "email@example.com"}} }]
+      def array_to_xml_hash(merge_fields_array)
+        merge_fields = []
+        merge_fields_array.each do |merge_field_hash|
+          name, value = merge_field_hash.first
+          merge_fields << { :merge_field => {:value => value, "@merge_field_name" => name}}
+        end
+
+        merge_fields
+      end
+
+    end
+  end
+  
+  def array_to_acceptable_names_hash(acceptable_names)
+    converted_fields = []
+    acceptable_names.each do |name|
+      converted_fields << {:name => name}
+    end
+    
+    converted_fields
+  end
+end

data/lib/rightsignature/template.rb

@@ -0,0 +1,177 @@
+module RightSignature
+  class Template
+    extend RightSignature::Helpers
+
+    class << self
+      
+      # List Templates and passes in optional options.
+      #  Options:
+      #   * page: page number
+      #   * per_page: number of templates to return per page. 
+      #       API only supports 10, 20, 30, 40, or 50. Default is 10.
+      #   * tags: filter templates by given tags. Array of strings, for name/value tags colon (:) should separate name and value.
+      #       Ex. "single_tag,tag_key:tag_value" would find templates with 'single_tag' and the name/value of 'tag_key' with value 'tag_value'.
+      #   * search: term to search for in templates.
+      def list(options={})
+        options[:tags] = TagsHelper.mixed_array_to_string_array(options[:tags]) if options[:tags]
+        RightSignature::Connection.get "/api/templates.xml", options
+      end
+      
+      def details(guid)
+        RightSignature::Connection.get "/api/templates/#{guid}.xml", {}
+      end
+      
+      # Clones a template so it can be used for sending. Always first step in sending a template.
+      def prepackage(guid)
+        RightSignature::Connection.post "/api/templates/#{guid}/prepackage.xml", {}
+      end
+      
+      # Prefills template.
+      # * guid: templates guid. Ex. a_1_zcfdidf8fi23
+      # * subject: subject of the document that'll appear in email
+      # * roles: Recipients of the document, should be an array of role names and emails in a hash with keys as role_names. 
+      #     Ex. [{"Employee" => {:name => "John Employee", :email => "john@employee.com"}}]
+      #       is equivalent to 
+      #         <role role_name="Employee">
+      #           <name>John Employee</name>
+      #           <email>john@employee.com</email>
+      #         </role>
+      # * options: other optional values
+      #     - description: document description that'll appear in the email
+      #     - merge_fields: document merge fields, should be an array of merge_field_values in a hash with the merge_field_name.
+      #         Ex. [{"Salary" => "$1,000,000"}]
+      #           is equivalent to 
+      #             <merge_field merge_field_name="Salary">
+      #             <value>$1,000,000</value>
+      #             </merge_field>
+      #     - expires_in: number of days before expiring the document. API only allows 2,5,15, or 30.
+      #     - tags: document tags, an array of string or hashes 'single_tag' (for simple tag) or {'tag_name' => 'tag_value'} (for tuples pairs)
+      #         Ex. ['sent_from_api', {"user_id" => "32"}]
+      #     - callback_url: A URI encoded URL that specifies the location for API to POST a callback notification to when the document has been created and signed. 
+      #         Ex. "http://yoursite/callback"
+      # 
+      # Ex. call with all options used
+      #   RightSignature::Template.prefill(
+      #     "a_1_zcfdidf8fi23", 
+      #     "Your Employee Handbook", 
+      #     [{"employee" => {:name => "John Employee", :email => "john@employee.com"}}],
+      #     {
+      #       :description => "Please read over the handbook and sign it.",
+      #       :merge_fields => [
+      #         { "Department" => "Fun and games" },
+      #         { "Salary" => "$1,000,000" }
+      #       ],
+      #       :expires_in => 5,
+      #       :tags => [
+      #         {:name => 'sent_from_api'},
+      #         {:name => 'user_id', :value => '32'}
+      #       ],
+      #       :callback_url => "http://yoursite/callback"
+      #     })
+      def prefill(guid, subject, roles, options={})
+        xml_hash = {
+          :template => {
+            :guid => guid,
+            :action => "prefill",
+            :subject => subject
+          }
+        }
+        
+        xml_hash[:template][:roles] = RolesHelper.array_to_xml_hash(roles)
+        
+        # Optional arguments
+        xml_hash[:template][:merge_fields] = MergeFieldsHelper.array_to_xml_hash(options[:merge_fields]) if options[:merge_fields]        
+        xml_hash[:template][:tags] = TagsHelper.array_to_xml_hash(options[:tags]) if options[:tags]
+        [:expires_in, :description, :callback_url, :action].each do |other_option|
+          xml_hash[:template][other_option] = options[other_option] if options[other_option]
+        end
+
+        RightSignature::Connection.post "/api/templates.xml", xml_hash
+      end
+      
+      def prepackage_and_send(guid, subject, roles, options={})
+        response = prepackage(guid)
+        new_guid = response["template"]["guid"]
+        send_template(new_guid, subject, roles, options)
+      end
+      
+      # Sends template.
+      # * guid: templates guid. Ex. a_1_zcfdidf8fi23
+      # * subject: subject of the document that'll appear in email
+      # * roles: Recipients of the document, should be an array of role names and emails in a hash with keys as role_names. 
+      #     Ex. [{"Employee" => {:name => "John Employee", :email => "john@employee.com"}}]
+      #       is equivalent to 
+      #         <role role_name="Employee">
+      #           <name>John Employee</name>
+      #           <email>john@employee.com</email>
+      #         </role>
+      # * options: other optional values
+      #     - description: document description that'll appear in the email
+      #     - merge_fields: document merge fields, should be an array of merge_field_values in a hash with the merge_field_name.
+      #         Ex. [{"Salary" => "$1,000,000"}]
+      #           is equivalent to 
+      #             <merge_field merge_field_name="Salary">
+      #             <value>$1,000,000</value>
+      #             </merge_field>
+      #     - expires_in: number of days before expiring the document. API only allows 2,5,15, or 30.
+      #     - tags: document tags, an array of {:name => 'tag_name'} (for simple tag) or {:name => 'tag_name', :value => 'value'} (for tuples pairs)
+      #         Ex. [{:name => 'sent_from_api'}, {:name => "user_id", :value => "32"}]
+      #     - callback_url: A URI encoded URL that specifies the location for API to POST a callback notification to when the document has been created and signed. 
+      #         Ex. "http://yoursite/callback"
+      # 
+      # Ex. call with all options used
+      #   RightSignature::Template.prefill(
+      #     "a_1_zcfdidf8fi23", 
+      #     "Your Employee Handbook", 
+      #     [{"employee" => {:name => "John Employee", :email => "john@employee.com"}}],
+      #     {
+      #       :description => "Please read over the handbook and sign it.",
+      #       :merge_fields => [
+      #         { "Department" => "Fun and games" },
+      #         { "Salary" => "$1,000,000" }
+      #       ],
+      #       :expires_in => 5,
+      #       :tags => [
+      #         {:name => 'sent_from_api'},
+      #         {:name => 'user_id', :value => '32'}
+      #       ],
+      #       :callback_url => "http://yoursite/callback"
+      #     })
+      def send_template(guid, subject, roles, options={})
+        prefill(guid, subject, roles, options.merge({:action => 'send'}))
+      end
+      
+      # Creates a URL that give person ability to create a template in your account.
+      # * options: optional options for redirected person
+      #     - callback_location: URI encoded URL that specifies the location we will POST a callback notification to when the template has been created.
+      #     - redirect_location: A URI encoded URL that specifies the location we will redirect the user to, after they have created a template.
+      #     - tags: tags to add to the template. an array of 'tag_name' (for simple tag) or {'tag_name' => 'value'} (for tuples pairs)
+      #         Ex. ['created_from_api', {"user_id" => "123"}]
+      #     - acceptabled_role_names: The user creating the Template will be forced to select one of the values provided. 
+      #         There will be no free-form name entry when adding roles to the Template. An array of strings. 
+      #         Ex. ["Employee", "Employeer"]
+      #     - acceptable_merge_field_names: The user creating the Template will be forced to select one of the values provided. 
+      #         There will be no free-form name entry when adding merge fields to the Template.
+      #         Ex. ["Location", "Tax ID", "Company Name"]
+      def generate_build_url(options={})
+        xml_hash = {:template => {}}
+        xml_hash[:template][:tags] = TagsHelper.array_to_xml_hash(options[:tags]) if options[:tags]
+        
+        [:acceptable_merge_field_names, :acceptabled_role_names].each do |option|
+          xml_hash[:template][option] = array_to_acceptable_names_hash(options[option]) if options[option]
+        end
+        
+        [:callback_location, :redirect_location].each do |other_option|
+          xml_hash[:template][other_option] = options[other_option] if options[other_option]
+        end
+
+        response = RightSignature::Connection.post "/api/templates/generate_build_token.xml", xml_hash
+        
+        redirect_token = response["token"]["redirect_token"]
+        
+        "#{RightSignature::Connection.site}/builder/new?rt=#{redirect_token}"
+      end
+      
+    end
+  end
+end