docusign_rest 0.0.3 → 0.0.4

data/README.md

@@ -1,6 +1,6 @@
 # DocusignRest
 
-This 'wrapper gem' hooks a Ruby app (currently only tested with Rails) up to the DocuSign REST API to allow for embedded signing.
+This 'wrapper gem' hooks a Ruby app (currently only tested with Rails) up to the [DocuSign](http://www.docusign.com/) [REST API](http://www.docusign.com/developer-center) to allow for embedded signing.
 
 ## Installation
 
@@ -75,13 +75,14 @@ The above options allow you to change the endpoint (to be able to hit the produc
 
 The docusign\_rest gem makes creating multipart POST (aka file upload) requests to the DocuSign REST API dead simple. It's built on top of Net:HTTP and utilizes the [multipart-post](https://github.com/nicksieger/multipart-post) gem to assist with formatting the multipart requests. The DocuSign REST API requires that all files be embedded as JSON directly in the request body (not the body\_stream like multipart-post does by default) so the docusign\_rest gem takes care of [setting that up for you](https://github.com/j2fly/docusign_rest/blob/master/lib/docusign_rest/client.rb#L397). 
 
-This gem also monkey patches one small part of multipart-post to inject some header values and formatting that DocuSign requires. If you would like to see the monkey patched code please take a look at [lib/multipart-post/parts.rb](https://github.com/j2fly/docusign_rest/blob/master/lib/multipart_post/parts.rb). It's only re-opening one method, but feel free to make sure you understand that monkey patch if it concerns you. 
+This gem also monkey patches one small part of multipart-post to inject some header values and formatting that DocuSign requires. If you would like to see the monkey patched code please take a look at [lib/multipart-post/parts.rb](https://github.com/j2fly/docusign_rest/blob/master/lib/multipart_post/parts.rb). It's only re-opening one method, but feel free to make sure you understand that code if it concerns you. 
 
 ### Examples
 
-* These examples assume you have already run the `docusign_rest:generate_config` rake task and have the configure block properly setup in an initializer with your username, password, integrator\_key, and account\_id.
+* These examples assume you have already run the `docusign_rest:generate_config` rake task and have the configure block properly setup in an initializer with your username, password, integrator\_key, and account\_id. 
+* Unless noted otherwise, these requests return the JSON parsed body of the response so you can index the returned hash directly. For example: `template_response["templateId"]`.
 
-**Getting login information:**
+**Getting account_id:**
 
 ```ruby
 client = DocusignRest::Client.new
@@ -93,14 +94,14 @@ puts client.get_account_id
 
 ```ruby
 client = DocusignRest::Client.new
-response = client.create_envelope_from_document(
+document_envelope_response = client.create_envelope_from_document(
   email: {
     subject: "test email subject",
     body: "this is the email body and it's large!"
   },
   # If embedded is set to true  in the signers array below, emails
-  # don't go out and you can embed the signature page in an iFrame
-  # by using the get_recipient_view method
+  # don't go out to the signers and you can embed the signature page in an 
+  # iFrame by using the client.get_recipient_view method
   signers: [
     {
       #embedded: true,
@@ -110,16 +111,15 @@ response = client.create_envelope_from_document(
     {
       #embedded: true,
       name: 'Test Girl',
-      email: 'someone@gmail.com'
+      email: 'someone+else@gmail.com'
     }
   ],
   files: [
-    {path: 'test.pdf', name: 'test.pdf'},
-    {path: 'test2.pdf', name: 'test2.pdf'}
+    {path: '/Absolute/path/to/test.pdf', name: 'test.pdf'},
+    {path: '/Absolute/path/to/test2.pdf', name: 'test2.pdf'}
   ],
   status: 'sent'
 )
-response = JSON.parse(response.body)
 ```
 
 
@@ -127,23 +127,29 @@ response = JSON.parse(response.body)
 
 ```ruby
 client = DocusignRest::Client.new
-response = client.create_template(
-  description: 'Cool Description',
-  name: "Cool Template Name",
+@template_response = client.create_template(
+  description: 'Template Description',
+  name: "Template Name",
   signers: [
     {
       embedded: true,
       name: 'jon',
       email: 'someone@gmail.com',
       role_name: 'Issuer',
-      anchor_string: 'sign here'
+      anchor_string: 'issuer_sig'
+    },
+    {
+      embedded: true,
+      name: 'tim',
+      email: 'someone+else@gmail.com',
+      role_name: 'Attorney',
+      anchor_string: 'attorney_sig'
     }
   ],
   files: [
-    {path: 'test.pdf', name: 'test.pdf'}
+    {path: '/Absolute/path/to/test.pdf', name: 'test.pdf'}
   ]
 )
-@template_response = JSON.parse(response.body)
 ```
 
 
@@ -151,7 +157,7 @@ response = client.create_template(
 
 ```ruby
 client = DocusignRest::Client.new
-response = client.create_envelope_from_template(
+@envelope_response = client.create_envelope_from_template(
   status: 'sent',
   email: {
     subject: "The test email subject envelope",
@@ -164,28 +170,80 @@ response = client.create_envelope_from_template(
       name: 'jon',
       email: 'someone@gmail.com',
       role_name: 'Issuer'
+    },
+    {
+      embedded: true,
+      name: 'tim',
+      email: 'someone+else@gmail.com',
+      role_name: 'Attorney'
     }
   ]
 )
-@envelope_response = JSON.parse(response.body)
 ```
 
 
-**Retrieving the url for embedded signing**
+**Retrieving the url for embedded signing. (Returns a string, not a hash)**
 
 ```ruby
 client = DocusignRest::Client.new
-response = client.get_recipient_view(
+@url = client.get_recipient_view(
   envelope_id: @envelope_response["envelopeId"],
-  name: 'jon',
-  email: 'someone@gmail.com',
+  name: current_user.full_name,
+  email: current_user.email,
   return_url: 'http://google.com'
 )
-@view_recipient_response = JSON.parse(response.body)
-puts @view_recipient_response["url"]
 ```
 
 
+**Check status of an envelope including the signers hash w/ the status of each signer**
+
+```ruby
+client = DocusignRest::Client.new
+response = client.get_envelope_recipients(
+  envelope_id: @envelope_response["envelopeId"],
+  include_tabs: true,
+  include_extended: true
+)
+```
+
+
+## Breaking out of the iFrame after signing
+
+In order to return to your application after the signing process is complete it's important to have a way to evaluate whether or not the signing was successful and then do something about each case. The way I set this up was to render the embedded signing iframe for a controller action called 'embedded_signing' and specify the return_url of the `client.get_recipient_view` API call to be something like: http://myapp.com/docusign_response. Then in the same controller as the embedded_signing method, define the docusign_response method. This is where the signing process will redirect to after the user is done interacting with the DocuSign iframe. DocuSign passes a query string parameter in the return_url named 'event' and you can check like so: `if params[:event] == "signing_complete"` then you'll want to redirect to another spot in your app, not in the iframe. To do so, we need to use JavaScript to access the iframe's parent and set it's location to the path of our choosing. To do this, instanciate the DocusignRest::Utility class and call the breakout_path method like this:
+
+```ruby    
+class SomeController < ApplicationController
+
+  # the view corresponding to this action has the iFrame in it with the
+  # @url as it's src. @envelope_response is populated from either:
+  # @envelope_response = client.create_envelope_from_document
+  # or
+  # @envelope_response = client.create_envelope_from_template
+  def embedded_signing
+    client = DocusignRest::Client.new
+    @url = client.get_recipient_view(
+      envelope_id: @envelope_response["envelopeId"],
+      name: current_user.display_name,
+      email: current_user.email,
+      return_url: "http://localhost:3000/docusign_response"
+    )
+  end
+
+  def docusign_response
+    utility = DocusignRest::Utility.new
+
+    if params[:event] == "signing_complete"
+      flash[:notice] = "Thanks! Successfully signed"
+      render :text => utility.breakout_path(some_path), content_type: :html
+    else
+      flash[:notice] = "You chose not to sign the document."
+      render :text => utility.breakout_path(some_other_path), content_type: :html
+    end
+  end
+
+end
+```
+
 ## Contributing
 
 1. Fork it

data/lib/docusign_rest.rb

@@ -1,6 +1,7 @@
 require 'docusign_rest/version'
 require 'docusign_rest/configuration'
 require 'docusign_rest/client'
+require 'docusign_rest/utility'
 require 'multipart_post' #require the multipart-post gem itself
 require 'net/http/post/multipart' #require the multipart-post net/http/post/multipart monkey patch
 require 'multipart_post/parts' #require my monkey patched parts.rb which adjusts the build_part method

data/lib/docusign_rest/client.rb

@@ -243,8 +243,8 @@ module DocusignRest
           \"routingOrder\":#{index+1},
           \"socialAuthentications\":null,
           \"templateAccessCodeRequired\":false,
-          \"templateLocked\":#{signer[:template_locked] || 'false'},
-          \"templateRequired\":#{signer[:template_required] || 'false'},
+          \"templateLocked\":#{signer[:template_locked] || true},
+          \"templateRequired\":#{signer[:template_required] || true},
           \"email\":\"#{signer[:email]}\",
           \"name\":\"#{signer[:name]}\",
           \"autoNavigation\":false,
@@ -268,20 +268,24 @@ module DocusignRest
             \"signHereTabs\":[
               {
                 \"anchorString\":\"#{signer[:anchor_string]}\",
-                \"conditionalParentLabel\":null,
-                \"conditionalParentValue\":null,
+                \"anchorXOffset\": \"0\",
+                \"anchorYOffset\": \"0\",
+                \"anchorIgnoreIfNotPresent\": false,
+                \"anchorUnits\": \"pixels\",
+                \"conditionalParentLabel\": null,
+                \"conditionalParentValue\": null,
                 \"documentId\":\"#{signer[:document_id] || '1'}\",
                 \"pageNumber\":\"#{signer[:page_number] || '1'}\",
                 \"recipientId\":\"#{index+1}\",
-                \"templateLocked\":#{signer[:template_locked] || 'false'},
-                \"templateRequired\":#{signer[:template_required] || 'false'},
+                \"templateLocked\":#{signer[:template_locked] || true},
+                \"templateRequired\":#{signer[:template_required] || true},
                 \"xPosition\":\"#{signer[:x_position] || '0'}\",
                 \"yPosition\":\"#{signer[:y_position] || '0'}\",
                 \"name\":\"#{signer[:sign_here_tab_text] || 'Sign Here'}\",
                 \"optional\":false,
                 \"scaleValue\":1,
                 \"tabLabel\":\"#{signer[:tab_label] || 'Signature 1'}\"
-              }
+              },
             ],
             \"signerAttachmentTabs\":null,
             \"ssnTabs\":null,
@@ -425,7 +429,7 @@ module DocusignRest
     #                 sending at a later time
     # headers       - Allows a client to pass in some
     #
-    # Returns a response object containing:
+    # Returns a JSON parsed response object containing:
     #   envelopeId     - The envelope's ID
     #   status         - Sent, created, or voided
     #   statusDateTime - The date/time the envelope was created
@@ -454,7 +458,8 @@ module DocusignRest
                 )
 
       # Finally do the Net::HTTP request!
-      http.request(request)
+      response = http.request(request)
+      parsed_response = JSON.parse(response.body)
     end
 
 
@@ -482,7 +487,7 @@ module DocusignRest
     # headers       - Optional hash of headers to merge into the existing
     #                 required headers for a multipart request.
     #
-    # Returns a response body containing the template's:
+    # Returns a JSON parsed response body containing the template's:
     #   name - Name given above
     #   templateId - The auto-generated ID provided by DocuSign
     #   Uri - the URI where the template is located on the DocuSign servers
@@ -516,7 +521,8 @@ module DocusignRest
                 )
 
       # Finally do the Net::HTTP request!
-      http.request(request)
+      response = http.request(request)
+      parsed_response = JSON.parse(response.body)
     end
 
 
@@ -538,7 +544,7 @@ module DocusignRest
     # headers        - Optional hash of headers to merge into the existing
     #                  required headers for a multipart request.
     #
-    # Returns a response body containing the envelope's:
+    # Returns a JSON parsed response body containing the envelope's:
     #   name - Name given above
     #   templateId - The auto-generated ID provided by DocuSign
     #   Uri - the URI where the template is located on the DocuSign servers
@@ -558,13 +564,11 @@ module DocusignRest
 
       http = initialize_net_http_ssl(uri)
 
-      request = Net::HTTP::Post.new(
-                  uri.request_uri,
-                  headers(content_type)
-                )
+      request = Net::HTTP::Post.new(uri.request_uri, headers(content_type))
       request.body = post_body
 
-      http.request(request)
+      response = http.request(request)
+      parsed_response = JSON.parse(response.body)
     end
 
 
@@ -578,7 +582,7 @@ module DocusignRest
     # headers     - optional hash of headers to merge into the existing
     #               required headers for a multipart request.
     #
-    # Returns the URL for embedded signing which needs to be put in an iFrame
+    # Returns the URL string for embedded signing (can be put in an iFrame)
     def get_recipient_view(options={})
       content_type = {'Content-Type' => 'application/json'}
       content_type.merge(options[:headers]) if options[:headers]
@@ -595,15 +599,38 @@ module DocusignRest
 
       http = initialize_net_http_ssl(uri)
 
-      request = Net::HTTP::Post.new(
-                  uri.request_uri,
-                  headers(content_type)
-                )
+      request = Net::HTTP::Post.new(uri.request_uri, headers(content_type))
       request.body = post_body
 
-      http.request(request)
+      response = http.request(request)
+      parsed_response = JSON.parse(response.body)
+      parsed_response["url"]
     end
 
+    # Public returns the envelope recipients for a given envelope
+    #
+    # include_tabs - boolean, determines if the tabs for each signer will be
+    #                returned in the response, defaults to false.
+    # envelope_id  - ID of the envelope for which you want to retrive the
+    #                signer info
+    # headers      - optional hash of headers to merge into the existing
+    #                required headers for a multipart request.
+    #
+    # Returns a hash of detailed info about the envelope including the signer
+    # hash and status of each signer
+    def get_envelope_recipients(options={})
+      content_type = {'Content-Type' => 'application/json'}
+      content_type.merge(options[:headers]) if options[:headers]
+
+      include_tabs = options[:include_tabs] || false
+      include_extended = options[:include_extended] || false
+      uri = build_uri("/accounts/#{@acct_id}/envelopes/#{options[:envelope_id]}/recipients?include_tabs=#{include_tabs}&include_extended=#{include_extended}")
+
+      http = initialize_net_http_ssl(uri)
+      request = Net::HTTP::Get.new(uri.request_uri, headers(content_type))
+      response = http.request(request)
+      parsed_response = JSON.parse(response.body)
+    end
   end
 
 end

data/lib/docusign_rest/utility.rb

@@ -0,0 +1,54 @@
+module DocusignRest
+
+  class Utility
+    # Public takes a path to redirect to and breaks the redirect out of an iFrame
+    #
+    # This can be used after embedded signing is either successful or not and has
+    # been redirected to a controller action (like docusign_response for instance)
+    # where the return from the signing process can be evaluated. If successful
+    # use this to redirect to one place, otherwise redirect to another place. You
+    # can use params[:event] to evaluate whether or not the signing was successful
+    #
+    # path - a relative or absolute path or rails helper can be passed in
+    #
+    # Example
+    #
+    #   class SomeController < ApplicationController
+    #
+    #     # the view corresponding to this action has the iFrame in it with the
+    #     # @url as it's src. @envelope_response is populated from either:
+    #     # @envelope_response = client.create_envelope_from_document
+    #     # or
+    #     # @envelope_response = client.create_envelope_from_template
+    #     def embedded_signing
+    #       client = DocusignRest::Client.new
+    #       @url = client.get_recipient_view(
+    #         envelope_id: @envelope_response["envelopeId"],
+    #         name: current_user.display_name,
+    #         email: current_user.email,
+    #         return_url: "http://localhost:3000/docusign_response"
+    #       )
+    #     end
+    #
+    #     def docusign_response
+    #       utility = DocusignRest::Utility.new
+    #
+    #       if params[:event] == "signing_complete"
+    #         flash[:notice] = "Thanks! Successfully signed"
+    #         render :text => utility.breakout_path(posts_path), content_type: :html
+    #       else
+    #         flash[:notice] = "You chose not to sign the document."
+    #         render :text => utility.breakout_path(logout_path), content_type: :html
+    #       end
+    #     end
+    #
+    #   end
+    #
+    # Returns a string of HTML including some JS to redirect to the passed in
+    # path but in the iFrame's parent.
+    def breakout_path(path)
+      "<html><body><script type='text/javascript' charset='utf-8'>parent.location.href = '#{path}';</script></body></html>"
+    end
+  end
+
+end

data/lib/docusign_rest/version.rb

@@ -1,3 +1,3 @@
 module DocusignRest
-  VERSION = "0.0.3"
+  VERSION = "0.0.4"
 end

data/test/docusign_rest/client_test.rb

@@ -109,7 +109,6 @@ describe DocusignRest::Client do
           ],
           status: 'sent'
         )
-        response = JSON.parse(response.body)
         response["status"].must_equal "sent"
       end
     end
@@ -118,7 +117,7 @@ describe DocusignRest::Client do
       before do
         # create the template dynamically
         VCR.use_cassette("create_template", record: :once)  do
-          response = @client.create_template(
+          @template_response = @client.create_template(
             description: 'Cool Description',
             name: "Cool Template Name",
             signers: [
@@ -138,12 +137,11 @@ describe DocusignRest::Client do
               {path: 'test.pdf', name: 'test.pdf'}
             ]
           )
-          @template_response = JSON.parse(response.body)
         end
 
         # use the templateId to get the envelopeId
         VCR.use_cassette("create_envelope/from_template", record: :once)  do
-          response = @client.create_envelope_from_template(
+          @envelope_response = @client.create_envelope_from_template(
             status: 'sent',
             email: {
               subject: "The test email subject envelope",
@@ -159,7 +157,6 @@ describe DocusignRest::Client do
               }
             ]
           )
-          @envelope_response = JSON.parse(response.body)
         end
       end
 
@@ -179,11 +176,22 @@ describe DocusignRest::Client do
             email: 'someone@gmail.com',
             return_url: 'http://google.com'
           )
-          @view_recipient_response = JSON.parse(response.body)
-          puts @view_recipient_response["url"]
+          response.must_match(/http/)
         end
       end
 
+      #status return values = "sent", "delivered", "completed"
+      it "should retrieve the envelope recipients status" do
+        VCR.use_cassette("get_envelope_recipients", record: :once)  do
+          response = @client.get_envelope_recipients(
+            envelope_id: @envelope_response["envelopeId"],
+            include_tabs: true,
+            include_extended: true
+          )
+          response["signers"].wont_be_nil
+          #puts response["signers"]
+        end
+      end
     end
 
   end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: docusign_rest
 version: !ruby/object:Gem::Version
-  version: 0.0.3
+  version: 0.0.4
   prerelease: 
 platform: ruby
 authors:
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2012-06-19 00:00:00.000000000 Z
+date: 2012-06-23 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: multipart-post
@@ -158,6 +158,7 @@ files:
 - lib/docusign_rest/client.rb
 - lib/docusign_rest/configuration.rb
 - lib/docusign_rest/railtie.rb
+- lib/docusign_rest/utility.rb
 - lib/docusign_rest/version.rb
 - lib/multipart_post/parts.rb
 - lib/tasks/docusign_task.rake