rightsignature 0.1.4 → 0.1.5

data/README.md

@@ -8,7 +8,7 @@ gem install rightsignature
 ```
 or in your Gemfile
 ```
-gem 'rightsignature', '~> 0.1.4'
+gem 'rightsignature', '~> 0.1.5'
 ```
 
 Setup
@@ -199,6 +199,7 @@ Optional options:
      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_merge_field_ids: Using merge field ids instead of merge field name for merge_fields. true or false.
 
 #####Template Prepacking
 For cloning a Template before sending it.
@@ -211,17 +212,20 @@ After prepacking, the new template can be updated with prefill data. This won't
 ```
 RightSignature::Template.prefill(guid, subject, roles)
 ```
-
-Optional options:
- * 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"}]
- * 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"
-
+ * guid: template guid to use. Should be a template that was prepackaged
+ * subject: document subject. 
+ * roles: recipient names in array of {:name => "Person's Name", :email => "Email"} hashed by Role ID. Ex. {"signer_A" => {:name => "Your Name", :name => "a@example.com"}}
+ * Optional options:
+   * 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"}]
+   * 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_merge_field_ids: Using merge field ids instead of merge field name for merge_fields. true or false.
+  
 ```
 options = {
   :description => "Please read over the handbook and sign it.",
@@ -245,16 +249,19 @@ Send template as a document for signing. Same options as prefill.
 ```
 RightSignature::Template.send_template(guid, subject, roles)
 ```
-
-Optional options:
- * 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"}]
- * 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"
+ * guid: template guid to use. Should be a template that was prepackaged
+ * subject: document subject. 
+ * roles: recipient names in array of {:name => "Person's Name", :email => "Email"} hashed by Role ID. Ex. {"signer_A" => {:name => "Your Name", :name => "a@example.com"}}
+ * Optional options:
+   * 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"}]
+   * 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_merge_field_ids: Using merge field ids instead of merge field name for merge_fields. true or false.
 
 ```
 options = {
@@ -280,7 +287,7 @@ Returns an array of {:name => "John Bellingham", "url" => "https://rightsignatur
 RightSignature::Template.send_as_embedded_signers(guid, recipients, options={})
 ```
  * guid: guid of template to create document with
- * recipient: recipient names in array of {"Role Name" => {:name => "Your Name"}}
+ * recipient: recipient names in array of {:name => "Person's Name"} hashed by Role ID. Ex. {"signer_A" => {:name => "Your Name"}}
  * options:
    * subject: document subject that'll appear in the email
    * description: document description that'll appear in the email
@@ -292,6 +299,7 @@ RightSignature::Template.send_as_embedded_signers(guid, recipients, options={})
    * 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"
    * redirect_location: URL to redirect users after signing.
+   * use_merge_field_ids: Using merge field ids instead of merge field name for merge_fields. true or false.
 
 #####Create New Template Link
 Generate a url that let's someone upload and create a template under OAuth user's account.

data/lib/rightsignature/helpers/normalizing.rb

@@ -34,14 +34,19 @@ module RightSignature::Helpers
   
   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"} }]
+      # Converts [{"Role_ID" => {:name => "John", :email => "email@example.com"}}] to 
+      #   [{:role => {:name => "John", :email => "email@example.com", "@role_id" => "Role_ID"} }]
+      # Tries to guess if it's using Role ID or 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})}
+          if name.match(/^signer_[A-Z]+$/) || name.match(/^cc_[A-Z]+$/)
+            roles_hash_array << {:role => value.merge({"@role_id" => name})}
+          else
+            roles_hash_array << {:role => value.merge({"@role_name" => name})}
+          end
         end
       
         roles_hash_array
@@ -55,11 +60,15 @@ module RightSignature::Helpers
     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)
+      def array_to_xml_hash(merge_fields_array, use_id=false)
         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}}
+          if use_id
+            merge_fields << { :merge_field => {:value => value, "@merge_field_id" => name}}
+          else
+            merge_fields << { :merge_field => {:value => value, "@merge_field_name" => name}}
+          end
         end
 
         merge_fields

data/lib/rightsignature/template.rb

@@ -80,7 +80,8 @@ module RightSignature
         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]        
+        use_merge_field_ids = options.delete(:use_merge_field_ids)
+        xml_hash[:template][:merge_fields] = MergeFieldsHelper.array_to_xml_hash(options[:merge_fields], use_merge_field_ids) 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]

data/lib/rightsignature/version.rb

@@ -1,3 +1,3 @@
 module RightSignature
-  VERSION = "0.1.4"
+  VERSION = "0.1.5"
 end

data/spec/normalizing_spec.rb

@@ -0,0 +1,67 @@
+require File.dirname(__FILE__) + '/spec_helper.rb'
+
+describe RightSignature::Helpers::TagsHelper do 
+  describe "mixed_array_to_string_array" do
+    it "should convert array of strings and hashes to string" do
+      RightSignature::Helpers::TagsHelper.mixed_array_to_string_array(["a", {'good' => "yea"}, '123']).should == "a,good:yea,123"
+    end
+    
+    it "should raise error if array contains something other than hash or string" do
+      lambda {RightSignature::Helpers::TagsHelper.mixed_array_to_string_array(["a", ['bad'], {'good' => "yea"}])}.should raise_error
+    end
+  end
+  
+  describe "array_to_xml_hash" do
+    it "should convert array of string and hash of {name => value} into array of :tag => {:name => name, :value => value}" do
+      RightSignature::Helpers::TagsHelper.array_to_xml_hash(['abc', {"taggy" => "tvalue"}]).should == [{:tag => {:name => 'abc'}}, {:tag => {:name => 'taggy', :value => 'tvalue'}}]
+    end
+  end
+end
+
+describe RightSignature::Helpers::RolesHelper do
+  describe "array_to_xml_hash" do
+    it "should convert array of {\"Role name\" => {:name => name, :email => email}} to array of {:role => {:name => name, :email => email, \"@role_id\" => \"Role name\"}} " do
+      results = RightSignature::Helpers::RolesHelper.array_to_xml_hash([
+        {"Leaser" => {:name => "John Bellingham", :email => "j@example.com"}}, 
+        {"Leasee" => {:name => "Timmy S", :email => "t@example.com"}}
+      ])
+      results.size.should == 2
+      results.include?({:role => {:name => "John Bellingham", :email => "j@example.com", "@role_name" => "Leaser"}})
+      results.include?({:role => {:name => "Timmy S", :email => "t@example.com", "@role_name" => "Leasee"}})
+    end
+
+    it "should convert array of {\"signer_A\" => {:name => name, :email => email}} or {\"cc_A\" => {:name => name, :email => email}} to array of {:role => {:name => name, :email => email, \"@role_id\" => \"signer_a\"}} " do
+      results = RightSignature::Helpers::RolesHelper.array_to_xml_hash([
+        {"signer_A" => {:name => "John Bellingham", :email => "j@example.com"}}, 
+        {"cc_A" => {:name => "Timmy S", :email => "t@example.com"}}
+      ])
+      results.size.should == 2
+      results.include?({:role => {:name => "John Bellingham", :email => "j@example.com", "@role_id" => "signer_A"}})
+      results.include?({:role => {:name => "Timmy S", :email => "t@example.com", "@role_id" => "cc_A"}})
+    end
+  end
+end
+
+describe RightSignature::Helpers::MergeFieldsHelper do
+  describe "array_to_xml_hash" do
+    it "should convert array of {\"Merge field name\" => \"Merge Field Value\"} to array of {:merge_field => {:value => \"Merge Field Value\", \"@merge_field_name\" => \"Merge Field Name\"}} " do
+      results = RightSignature::Helpers::MergeFieldsHelper.array_to_xml_hash([
+        {"City" => "Santa Barbara"},
+        {"Section" => "House"}
+      ])
+      results.size.should == 2
+      results.include?({:merge_field => {:value => "Santa Barbara", "@merge_field_name" => "City"}})
+      results.include?({:merge_field => {:value => "House", "@merge_field_name" => "Section"}})
+    end
+
+    it "should convert array of {\"Merge field name\" => \"Merge Field Value\"} to array of {:merge_field => {:value => \"Merge Field Value\", \"@merge_field_id\" => \"Merge Field Name\"}} " do
+      results = RightSignature::Helpers::MergeFieldsHelper.array_to_xml_hash([
+        {"1_abc_defg" => "Santa Barbara"},
+        {"2_345_789" => "House"}
+      ], true)
+      results.size.should == 2
+      results.include?({:merge_field => {:value => "Santa Barbara", "@merge_field_id" => "1_abc_defg"}})
+      results.include?({:merge_field => {:value => "House", "@merge_field_id" => "2_345_789"}})
+    end
+  end
+end

data/spec/template_spec.rb

@@ -80,6 +80,24 @@ describe RightSignature::Template do
       })
       RightSignature::Template.prefill("MYGUID", "sign me", [{"Employee" => {:name => "John Employee", :email => "john@employee.com"}}])
     end
+    
+    it "should add \"@role_id\"=>'signer_A' key to roles in xml hash" do
+      RightSignature::Connection.should_receive(:post).with('/api/templates.xml', {
+        :template => {
+          :guid => "MYGUID", 
+          :action => "prefill",
+          :subject => "sign me", 
+          :roles => [
+            {:role => {
+              :name => "John Employee", 
+              :email => "john@employee.com", 
+              "@role_id" => "signer_A"
+            }}
+          ]
+        }
+      })
+      RightSignature::Template.prefill("MYGUID", "sign me", [{"signer_A" => {:name => "John Employee", :email => "john@employee.com"}}])
+    end
 
     describe "optional options" do
       it "should add \"@merge_field_name\"=>'Tax_id' key to merge_fields in xml hash" do
@@ -96,6 +114,20 @@ describe RightSignature::Template do
         RightSignature::Template.prefill("MYGUID", "sign me", [], {:merge_fields => [{"Tax_id" => "123456"}]})
       end
 
+      it "should add \"@merge_field_id\"=>'123_abc_78' key to merge_fields in xml hash" do
+        RightSignature::Connection.should_receive(:post).with('/api/templates.xml', {
+          :template => {
+            :guid => "MYGUID", 
+            :action => "prefill",
+            :subject => "sign me", 
+            :roles => [
+            ],
+            :merge_fields => [{:merge_field => {:value => "123456", "@merge_field_id" => "123_abc_78"}}]
+          }
+        })
+        RightSignature::Template.prefill("MYGUID", "sign me", [], {:merge_fields => [{"123_abc_78" => "123456"}], :use_merge_field_ids => true})
+      end
+
       it "should add \"tag\" key to tags in xml hash" do
         RightSignature::Connection.should_receive(:post).with('/api/templates.xml', {
           :template => {

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: rightsignature
 version: !ruby/object:Gem::Version
-  version: 0.1.4
+  version: 0.1.5
   prerelease: 
 platform: ruby
 authors:
@@ -136,6 +136,7 @@ files:
 - spec/connection_spec.rb
 - spec/document_spec.rb
 - spec/errors_spec.rb
+- spec/normalizing_spec.rb
 - spec/oauth_connnection_spec.rb
 - spec/spec_helper.rb
 - spec/template_spec.rb