Class: DocusignRest::Client

Inherits:
Object
  • Object
show all
Defined in:
lib/docusign_rest/client.rb

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(options = {}) ⇒ Client

Returns a new instance of Client.



10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
 
# File 'lib/docusign_rest/client.rb', line 10

def initialize(options={})
  # Merge the config values from the module and those passed to the client.
  merged_options = DocusignRest.options.merge(options)

  # Copy the merged values to this client and ignore those not part
  # of our configuration
  Configuration::VALID_CONFIG_KEYS.each do |key|
    send("#{key}=", merged_options[key])
  end

  # Set up the DocuSign Authentication headers with the values passed from
  # our config block
  if access_token.nil?
    @docusign_authentication_headers = {
      'X-DocuSign-Authentication' => {
        'Username' => username,
        'Password' => password,
        'IntegratorKey' => integrator_key
      }.to_json
    }
  else
    @docusign_authentication_headers = {
      'Authorization' => "Bearer #{access_token}"
    }
  end

  # Set the account_id from the configure block if present, but can't call
  # the instance var @account_id because that'll override the attr_accessor
  # that is automatically configured for the configure block
  @acct_id = 
end

Instance Attribute Details

#acct_id ⇒ Object

Returns the value of attribute acct_id.



8
9
10
 
# File 'lib/docusign_rest/client.rb', line 8

def acct_id
  @acct_id
end

#docusign_authentication_headers ⇒ Object

Returns the value of attribute docusign_authentication_headers.



8
9
10
 
# File 'lib/docusign_rest/client.rb', line 8

def docusign_authentication_headers
  @docusign_authentication_headers
end

Instance Method Details

#build_uri(url) ⇒ Object

Internal: builds a URI based on the configurable endpoint, api_version, and the passed in relative url

url - a relative url requiring a leading forward slash

Example:

build_uri('/login_information')

Returns a parsed URI object



81
82
83
 
# File 'lib/docusign_rest/client.rb', line 81

def build_uri(url)
  URI.parse("#{endpoint}/#{api_version}#{url}")
end

#convert_hash_keys(value) ⇒ Object

TODO (2014-02-03) jonk => document



1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
 
# File 'lib/docusign_rest/client.rb', line 1012

def convert_hash_keys(value)
  case value
  when Array
    value.map { |v| convert_hash_keys(v) }
  when Hash
    Hash[value.map { |k, v| [k.to_s.camelize(:lower), convert_hash_keys(v)] }]
  else
    value
  end
end

#create_account(options) ⇒ Object

TODO (2014-02-03) jonk => document



995
996
997
998
999
1000
1001
1002
1003
1004
1005
1006
1007
1008
 
# File 'lib/docusign_rest/client.rb', line 995

def (options)
  content_type = { 'Content-Type' => 'application/json' }
  content_type.merge(options[:headers]) if options[:headers]

  uri = build_uri('/accounts')

  post_body = convert_hash_keys(options).to_json

  http = initialize_net_http_ssl(uri)
  request = Net::HTTP::Post.new(uri.request_uri, headers(content_type))
  request.body = post_body
  response = http.request(request)
  JSON.parse(response.body)
end

#create_envelope_from_document(options = {}) ⇒ Object

Public: creates an envelope from a document directly without a template

file_io - Optional: an opened file stream of data (if you don’t

want to save the file to the file system as an incremental
step)

file_path - Required if you don’t provide a file_io stream, this is

the local path of the file you wish to upload. Absolute
paths recommended.

file_name - The name you want to give to the file you are uploading content_type - (for the request body) application/json is what DocuSign

is expecting

email_subject - (Optional) short subject line for the email email_body - (Optional) custom text that will be injected into the

DocuSign generated email

signers - A hash of users who should receive the document and need

to sign it. More info about the options available for
this method are documented above it's method definition.

status - Options include: ‘sent’, ‘created’, ‘voided’ and determine

if the envelope is sent out immediately or stored for
sending at a later time

headers - Allows a client to pass in some

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
uri            - The relative envelope uri



554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
 
# File 'lib/docusign_rest/client.rb', line 554

def create_envelope_from_document(options={})
  ios = create_file_ios(options[:files])
  file_params = create_file_params(ios)

  post_body = {
    emailBlurb:   "#{options[:email][:body] if options[:email]}",
    emailSubject: "#{options[:email][:subject] if options[:email]}",
    documents: get_documents(ios),
    recipients: {
      signers: get_signers(options[:signers])
    },
    status: "#{options[:status]}"
  }.to_json

  uri = build_uri("/accounts/#{acct_id}/envelopes")

  http = initialize_net_http_ssl(uri)

  request = initialize_net_http_multipart_post_request(
              uri, post_body, file_params, headers(options[:headers])
            )

  response = http.request(request)
  JSON.parse(response.body)
end

#create_envelope_from_template(options = {}) ⇒ Object

Public: create an envelope for delivery from a template

headers - Optional hash of headers to merge into the existing

required headers for a POST request.

status - Options include: ‘sent’, ‘created’, ‘voided’ and

determine if the envelope is sent out immediately or
stored for sending at a later time

email/body - Sets the text in the email body email/subject - Sets the text in the email subject line template_id - The id of the template upon which we want to base this

envelope

template_roles - See the get_template_roles method definition for a list

of options to pass. Note: for consistency sake we call
this 'signers' and not 'templateRoles' when we build up
the request in client code.

headers - Optional hash of headers to merge into the existing

required headers for a multipart request.

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



677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
 
# File 'lib/docusign_rest/client.rb', line 677

def create_envelope_from_template(options={})
  content_type = { 'Content-Type' => 'application/json' }
  content_type.merge(options[:headers]) if options[:headers]

  post_body = {
    status:             options[:status],
    emailBlurb:         options[:email][:body],
    emailSubject:       options[:email][:subject],
    templateId:         options[:template_id],
    eventNotification:  get_event_notification(options[:event_notification]),
    templateRoles:      get_template_roles(options[:signers])
   }.to_json

  uri = build_uri("/accounts/#{acct_id}/envelopes")

  http = initialize_net_http_ssl(uri)

  request = Net::HTTP::Post.new(uri.request_uri, headers(content_type))
  request.body = post_body

  response = http.request(request)
  JSON.parse(response.body)
end

#create_file_ios(files) ⇒ Object

Internal: sets up the file ios array

files - a hash of file params

Returns the properly formatted ios used to build the file_params hash



426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
 
# File 'lib/docusign_rest/client.rb', line 426

def create_file_ios(files)
  # UploadIO is from the multipart-post gem's lib/composite_io.rb:57
  # where it has this documentation:
  #
  # ********************************************************************
  # Create an upload IO suitable for including in the params hash of a
  # Net::HTTP::Post::Multipart.
  #
  # Can take two forms. The first accepts a filename and content type, and
  # opens the file for reading (to be closed by finalizer).
  #
  # The second accepts an already-open IO, but also requires a third argument,
  # the filename from which it was opened (particularly useful/recommended if
  # uploading directly from a form in a framework, which often save the file to
  # an arbitrarily named RackMultipart file in /tmp).
  #
  # Usage:
  #
  #     UploadIO.new('file.txt', 'text/plain')
  #     UploadIO.new(file_io, 'text/plain', 'file.txt')
  # ********************************************************************
  #
  # There is also a 4th undocumented argument, opts={}, which allows us
  # to send in not only the Content-Disposition of 'file' as required by
  # DocuSign, but also the documentId parameter which is required as well
  #
  ios = []
  files.each_with_index do |file, index|
    ios << UploadIO.new(
             file[:io] || file[:path],
             file[:content_type] || 'application/pdf',
             file[:name],
             'Content-Disposition' => "file; documentid=#{index + 1}"
           )
  end
  ios
end

#create_file_params(ios) ⇒ Object

Internal: sets up the file_params for inclusion in a multipart post request

ios - An array of UploadIO formatted file objects

Returns a hash of files params suitable for inclusion in a multipart post request



471
472
473
474
475
476
477
478
 
# File 'lib/docusign_rest/client.rb', line 471

def create_file_params(ios)
  # multi-doc uploading capabilities, each doc needs to be it's own param
  file_params = {}
  ios.each_with_index do |io,index|
    file_params.merge!("file#{index + 1}" => io)
  end
  file_params
end

#create_template(options = {}) ⇒ Object

Public: allows a template to be dynamically created with several options.

files - An array of hashes of file parameters which will be used

to create actual files suitable for upload in a multipart
request.

Options: io, path, name. The io is optional and would
require creating a file_io object to embed as the first
argument of any given file hash. See the create_file_ios
method definition above for more details.

email/body - (Optional) sets the text in the email. Note: the envelope

seems to override this, not sure why it needs to be
configured here as well. I usually leave it blank.

email/subject - (Optional) sets the text in the email. Note: the envelope

seems to override this, not sure why it needs to be
configured here as well. I usually leave it blank.

signers - An array of hashes of signers. See the

get_signers method definition for options.

description - The template description name - The template name headers - Optional hash of headers to merge into the existing

required headers for a multipart request.

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



609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
 
# File 'lib/docusign_rest/client.rb', line 609

def create_template(options={})
  ios = create_file_ios(options[:files])
  file_params = create_file_params(ios)

  post_body = {
    emailBlurb: "#{options[:email][:body] if options[:email]}",
    emailSubject: "#{options[:email][:subject] if options[:email]}",
    documents: get_documents(ios),
    recipients: {
      signers: get_signers(options[:signers], template: true)
    },
    envelopeTemplateDefinition: {
      description: options[:description],
      name: options[:name],
      pageCount: 1,
      password: '',
      shared: false
    }
  }.to_json

  uri = build_uri("/accounts/#{acct_id}/templates")
  http = initialize_net_http_ssl(uri)

  request = initialize_net_http_multipart_post_request(
              uri, post_body, file_params, headers(options[:headers])
            )

  response = http.request(request)
  JSON.parse(response.body)
end

#delete_account(account_id, options = {}) ⇒ Object

TODO (2014-02-03) jonk => document



1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
 
# File 'lib/docusign_rest/client.rb', line 1025

def (, options = {})
  content_type = { 'Content-Type' => 'application/json' }
  content_type.merge(options[:headers]) if options[:headers]

  uri = build_uri("/accounts/#{}")

  http = initialize_net_http_ssl(uri)
  request = Net::HTTP::Delete.new(uri.request_uri, headers(content_type))
  response = http.request(request)
  json = response.body
  json = '{}' if json.nil? || json == ''
  JSON.parse(json)
end

#get_account_id ⇒ Object

Internal: uses the get_login_information method to determine the client’s accountId and then caches that value into an instance variable so we don’t end up hitting the API for login_information more than once per request.

This is used by the rake task in lib/tasks/docusign_task.rake to add the config/initialzers/docusign_rest.rb file with the proper config block which includes the account_id in it. That way we don’t require hitting the /login_information URI in normal requests

Returns the accountId string



186
187
188
189
190
191
192
193
194
195
 
# File 'lib/docusign_rest/client.rb', line 186

def 
  unless acct_id
    response = .body
    hashed_response = JSON.parse(response)
     = hashed_response['loginAccounts']
    acct_id ||= .first['accountId']
  end

  acct_id
end

#get_console_view(options = {}) ⇒ Object

Public returns the URL for embedded console

envelope_id - the ID of the envelope you wish to use for embedded signing headers - optional hash of headers to merge into the existing

required headers for a multipart request.

Returns the URL string for embedded console (can be put in an iFrame)



766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
 
# File 'lib/docusign_rest/client.rb', line 766

def get_console_view(options={})
  content_type = { 'Content-Type' => 'application/json' }
  content_type.merge(options[:headers]) if options[:headers]

  post_body = {
    envelopeId: options[:envelope_id]
  }.to_json

  uri = build_uri("/accounts/#{acct_id}/views/console")

  http = initialize_net_http_ssl(uri)

  request = Net::HTTP::Post.new(uri.request_uri, headers(content_type))
  request.body = post_body

  response = http.request(request)

  parsed_response = JSON.parse(response.body)
  parsed_response['url']
end

#get_document_from_envelope(options = {}) ⇒ Object

Public retrieves the attached file from a given envelope

envelope_id - ID of the envelope from which the doc will be retrieved document_id - ID of the document to retrieve local_save_path - Local absolute path to save the doc to including the

filename itself

headers - Optional hash of headers to merge into the existing

required headers for a multipart request.

Example

client.get_document_from_envelope(
  envelope_id: @envelope_response['envelopeId'],
  document_id: 1,
  local_save_path: 'docusign_docs/file_name.pdf',
  return_stream: true/false # will return the bytestream instead of saving doc to file system.
)

Returns the PDF document as a byte stream.



877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
 
# File 'lib/docusign_rest/client.rb', line 877

def get_document_from_envelope(options={})
  content_type = { 'Content-Type' => 'application/json' }
  content_type.merge(options[:headers]) if options[:headers]

  uri = build_uri("/accounts/#{acct_id}/envelopes/#{options[:envelope_id]}/documents/#{options[:document_id]}")

  http = initialize_net_http_ssl(uri)
  request = Net::HTTP::Get.new(uri.request_uri, headers(content_type))
  response = http.request(request)
  return response.body if options[:return_stream]

  split_path = options[:local_save_path].split('/')
  split_path.pop #removes the document name and extension from the array
  path = split_path.join("/") #rejoins the array to form path to the folder that will contain the file

  FileUtils.mkdir_p(path)
  File.open(options[:local_save_path], 'wb') do |output|
    output << response.body
  end
end

#get_documents(ios) ⇒ Object

Internal: takes in an array of hashes of documents and calculates the documentId

Returns a hash of documents that are to be uploaded



485
486
487
488
489
490
491
492
 
# File 'lib/docusign_rest/client.rb', line 485

def get_documents(ios)
  ios.each_with_index.map do |io, index|
    {
      documentId: "#{index + 1}",
      name: io.original_filename
    }
  end
end

#get_documents_from_envelope(options = {}) ⇒ Object

Public retrieves the document infos from a given envelope

envelope_id - ID of the envelope from which document infos are to be retrieved

Returns a hash containing the envelopeId and the envelopeDocuments array



904
905
906
907
908
909
910
911
912
913
914
915
 
# File 'lib/docusign_rest/client.rb', line 904

def get_documents_from_envelope(options={})
  content_type = { 'Content-Type' => 'application/json' }
  content_type.merge(options[:headers]) if options[:headers]

  uri = build_uri("/accounts/#{acct_id}/envelopes/#{options[:envelope_id]}/documents")

  http     = initialize_net_http_ssl(uri)
  request  = Net::HTTP::Get.new(uri.request_uri, headers(content_type))
  response = http.request(request)

  JSON.parse(response.body)
end

#get_envelope(envelope_id) ⇒ Object

Grabs envelope data. Equivalent to the following call in the API explorer: Get Envelopev2/accounts/:accountId/envelopes/:envelopeId

envelope_id- DS id of envelope to be retrieved.



1061
1062
1063
1064
1065
1066
1067
1068
1069
 
# File 'lib/docusign_rest/client.rb', line 1061

def get_envelope(envelope_id)
  content_type = { 'Content-Type' => 'application/json' }
  uri = build_uri("/accounts/#{acct_id}/envelopes/#{envelope_id}")

  http = initialize_net_http_ssl(uri)
  request = Net::HTTP::Get.new(uri.request_uri, headers(content_type))
  response = http.request(request)
  JSON.parse(response.body)
end

#get_envelope_recipients(options = {}) ⇒ Object

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



799
800
801
802
803
804
805
806
807
808
809
810
811
 
# File 'lib/docusign_rest/client.rb', line 799

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)
  JSON.parse(response.body)
end

#get_envelope_status(options = {}) ⇒ Object

Public retrieves the envelope status

envelope_id - ID of the envelope from which the doc will be retrieved



817
818
819
820
821
822
823
824
825
826
827
 
# File 'lib/docusign_rest/client.rb', line 817

def get_envelope_status(options={})
  content_type = { 'Content-Type' => 'application/json' }
  content_type.merge(options[:headers]) if options[:headers]

  uri = build_uri("/accounts/#{acct_id}/envelopes/#{options[:envelope_id]}")

  http = initialize_net_http_ssl(uri)
  request = Net::HTTP::Get.new(uri.request_uri, headers(content_type))
  response = http.request(request)
  JSON.parse(response.body)
end

#get_envelope_statuses(options = {}) ⇒ Object

Public retrieves the statuses of envelopes matching the given query

from_date - Docusign formatted Date/DateTime. Only return items after this date.

to_date - Docusign formatted Date/DateTime. Only return items up to this date.

Defaults to the time of the call.

from_to_status - The status of the envelope checked for in the from_date - to_date period.

Defaults to 'changed'

status - The current status of the envelope. Defaults to any status.

Returns an array of hashes containing envelope statuses, ids, and similar information.



843
844
845
846
847
848
849
850
851
852
853
854
855
 
# File 'lib/docusign_rest/client.rb', line 843

def get_envelope_statuses(options={})
  content_type = { 'Content-Type' => 'application/json' }
  content_type.merge(options[:headers]) if options[:headers]

  query_params = options.slice(:from_date, :to_date, :from_to_status, :status)
  uri = build_uri("/accounts/#{acct_id}/envelopes?#{query_params.to_query}")

  http     = initialize_net_http_ssl(uri)
  request  = Net::HTTP::Get.new(uri.request_uri, headers(content_type))
  response = http.request(request)

  JSON.parse(response.body)
end

#get_event_notification(event_notification) ⇒ Object

TODO (2014-02-03) jonk => document



254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
 
# File 'lib/docusign_rest/client.rb', line 254

def get_event_notification(event_notification)
  return {} unless event_notification
  {
    useSoapInterface:          event_notification[:use_soap_interface] || false,
    includeCertificatWithSoap: event_notification[:include_certificate_with_soap] || false,
    url:                       event_notification[:url],
    loggingEnabled:            event_notification[:logging],
    'EnvelopeEvents' => Array(event_notification[:envelope_events]).map do |envelope_event|
      {
        includeDocuments:        envelope_event[:include_documents] || false,
        envelopeEventStatusCode: envelope_event[:envelope_event_status_code]
      }
    end
  }
end

#get_login_information(options = {}) ⇒ Object

Public: gets info necessary to make additional requests to the DocuSign API

options - hash of headers if the client wants to override something

Examples:

client = DocusignRest::Client.new
response = client.
puts response.body

Returns:

accountId - For the username, password, and integrator_key specified
baseUrl   - The base URL for all future DocuSign requests
email     - The email used when signing up for DocuSign
isDefault - # TODO identify what this is
name      - The account name provided when signing up for DocuSign
userId    - # TODO determine what this is used for, if anything
userName  - Full name provided when signing up for DocuSign



167
168
169
170
171
172
 
# File 'lib/docusign_rest/client.rb', line 167

def (options={})
  uri = build_uri('/login_information')
  request = Net::HTTP::Get.new(uri.request_uri, headers(options[:headers]))
  http = initialize_net_http_ssl(uri)
  http.request(request)
end

#get_recipient_names(options = {}) ⇒ Object

Public returns the names specified for a given email address (existing docusign user)

email - the email of the recipient headers - optional hash of headers to merge into the existing

required headers for a multipart request.

Returns the list of names



709
710
711
712
713
714
715
716
717
718
719
720
721
 
# File 'lib/docusign_rest/client.rb', line 709

def get_recipient_names(options={})
  content_type = { 'Content-Type' => 'application/json' }
  content_type.merge(options[:headers]) if options[:headers]

  uri = build_uri("/accounts/#{acct_id}/recipient_names?email=#{options[:email]}")

  http = initialize_net_http_ssl(uri)

  request = Net::HTTP::Post.new(uri.request_uri, headers(content_type))

  response = http.request(request)
  JSON.parse(response.body)
end

#get_recipient_view(options = {}) ⇒ Object

Public returns the URL for embedded signing

envelope_id - the ID of the envelope you wish to use for embedded signing name - the name of the signer email - the email of the recipient return_url - the URL you want the user to be directed to after he or she

completes the document signing

headers - optional hash of headers to merge into the existing

required headers for a multipart request.

Returns the URL string for embedded signing (can be put in an iFrame)



735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
 
# File 'lib/docusign_rest/client.rb', line 735

def get_recipient_view(options={})
  content_type = { 'Content-Type' => 'application/json' }
  content_type.merge(options[:headers]) if options[:headers]

  post_body = {
    authenticationMethod: 'email',
    clientUserId:         options[:client_id] || options[:email],
    email:                options[:email],
    returnUrl:            options[:return_url],
    userName:             options[:name]
  }.to_json

  uri = build_uri("/accounts/#{acct_id}/envelopes/#{options[:envelope_id]}/views/recipient")

  http = initialize_net_http_ssl(uri)

  request = Net::HTTP::Post.new(uri.request_uri, headers(content_type))
  request.body = post_body

  response = http.request(request)
  JSON.parse(response.body)
end

#get_signer_tabs(tabs) ⇒ Object

TODO (2014-02-03) jonk => document



240
241
242
243
244
245
246
247
248
249
250
 
# File 'lib/docusign_rest/client.rb', line 240

def get_signer_tabs(tabs)
  Array(tabs).map do |tab|
    {
      'tabLabel' => tab[:label],
      'name' => tab[:name],
      'value' => tab[:value],
      'documentId' => tab[:document_id],
      'selected' => tab[:selected]
    }
  end
end

#get_signers(signers, options = {}) ⇒ Object

Internal: takes an array of hashes of signers required to complete a document and allows for setting several options. Not all options are currently dynamic but that’s easy to change/add which I (and I’m sure others) will be doing in the future.

template - Includes other optional fields only used when

being called from a template

email - The signer’s email name - The signer’s name embedded - Tells DocuSign if this is an embedded signer which

determines weather or not to deliver emails. Also
lets us authenticate them when they go to do
embedded signing. Behind the scenes this is setting
the clientUserId value to the signer's email.

email_notification - Send an email or not role_name - The signer’s role, like ‘Attorney’ or ‘Client’, etc. template_locked - Doesn’t seem to work/do anything template_required - Doesn’t seem to work/do anything anchor_string - The string of text to anchor the ‘sign here’ tab to document_id - If the doc you want signed isn’t the first doc in

the files options hash

page_number - Page number of the sign here tab x_position - Distance horizontally from the anchor string for the

'sign here' tab to appear. Note: doesn't seem to
currently work.

y_position - Distance vertically from the anchor string for the

'sign here' tab to appear. Note: doesn't seem to
currently work.

sign_here_tab_text - Instead of ‘sign here’. Note: doesn’t work tab_label - TODO: figure out what this is



301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
 
# File 'lib/docusign_rest/client.rb', line 301

def get_signers(signers, options={})
  doc_signers = []

  signers.each_with_index do |signer, index|
    doc_signer = {
      email:                                 signer[:email],
      name:                                  signer[:name],
      accessCode:                            '',
      addAccessCodeToEmail:                  false,
      customFields:                          nil,
      iDCheckConfigurationName:              nil,
      iDCheckInformationInput:               nil,
      inheritEmailNotificationConfiguration: false,
      note:                                  '',
      phoneAuthentication:                   nil,
      recipientAttachment:                   nil,
      recipientId:                           "#{index + 1}",
      requireIdLookup:                       false,
      roleName:                              signer[:role_name],
      routingOrder:                          index + 1,
      socialAuthentications:                 nil
    }

    if signer[:email_notification]
      doc_signer[:emailNotification] = signer[:email_notification]
    end

    if signer[:embedded]
      doc_signer[:clientUserId] = signer[:client_id] || signer[:email]
    end

    if options[:template] == true
      doc_signer[:templateAccessCodeRequired] = false
      doc_signer[:templateLocked]             = signer[:template_locked].nil? ? true : signer[:template_locked]
      doc_signer[:templateRequired]           = signer[:template_required].nil? ? true : signer[:template_required]
    end

    doc_signer[:autoNavigation]   = false
    doc_signer[:defaultRecipient] = false
    doc_signer[:signatureInfo]    = nil
    doc_signer[:tabs]             = {
      approveTabs:          nil,
      checkboxTabs:         get_tabs(signer[:checkbox_tabs], options, index),
      companyTabs:          nil,
      dateSignedTabs:       get_tabs(signer[:date_signed_tabs], options, index),
      dateTabs:             nil,
      declineTabs:          nil,
      emailTabs:            get_tabs(signer[:email_tabs], options, index),
      envelopeIdTabs:       nil,
      fullNameTabs:         get_tabs(signer[:full_name_tabs], options, index),
      listTabs:             get_tabs(signer[:list_tabs], options, index),
      noteTabs:             nil,
      numberTabs:           nil,
      radioGroupTabs:       nil,
      initialHereTabs:      get_tabs(signer[:initial_here_tabs], options.merge!(initial_here_tab: true), index),
      signHereTabs:         get_tabs(signer[:sign_here_tabs], options.merge!(sign_here_tab: true), index),
      signerAttachmentTabs: nil,
      ssnTabs:              nil,
      textTabs:             get_tabs(signer[:text_tabs], options, index),
      titleTabs:            get_tabs(signer[:title_tabs], options, index),
      zipTabs:              nil
    }

    # append the fully build string to the array
    doc_signers << doc_signer
  end
  doc_signers
end

#get_tabs(tabs, options, index) ⇒ Object

TODO (2014-02-03) jonk => document



372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
 
# File 'lib/docusign_rest/client.rb', line 372

def get_tabs(tabs, options, index)
  tab_array = []

  Array(tabs).map do |tab|
    tab_hash = {}

    if tab[:anchor_string]
      tab_hash[:anchorString]             = tab[:anchor_string]
      tab_hash[:anchorXOffset]            = tab[:anchor_x_offset] || '0'
      tab_hash[:anchorYOffset]            = tab[:anchor_y_offset] || '0'
      tab_hash[:anchorIgnoreIfNotPresent] = tab[:ignore_anchor_if_not_present] || false
      tab_hash[:anchorUnits]              = 'pixels'
    end

    tab_hash[:conditionalParentLabel]   = nil
    tab_hash[:conditionalParentValue]   = nil
    tab_hash[:documentId]               = tab[:document_id] || '1'
    tab_hash[:pageNumber]               = tab[:page_number] || '1'
    tab_hash[:recipientId]              = index + 1
    tab_hash[:required]                 = tab[:required] || false

    if options[:template] == true
      tab_hash[:templateLocked]   = tab[:template_locked].nil? ? true : tab[:template_locked]
      tab_hash[:templateRequired] = tab[:template_required].nil? ? true : tab[:template_required]
    end

    if options[:sign_here_tab] == true || options[:initial_here_tab] == true
      tab_hash[:scaleValue] = tab_hash[:scaleValue] || 1
    end

    tab_hash[:xPosition]  = tab[:x_position] || '0'
    tab_hash[:yPosition]  = tab[:y_position] || '0'
    tab_hash[:name]       = tab[:name] if tab[:name]
    tab_hash[:optional]   = false
    tab_hash[:tabLabel]   = tab[:label] || 'Signature 1'
    tab_hash[:width]      = tab[:width] if tab[:width]
    tab_hash[:height]     = tab[:height] if tab[:width]
    tab_hash[:value]      = tab[:value] if tab[:value]

    tab_hash[:locked]     = tab[:locked] || false

    tab_hash[:list_items] = tab[:list_items] if tab[:list_items]

    tab_array << tab_hash
  end
  tab_array
end

#get_template(template_id, options = {}) ⇒ Object

TODO (2014-02-03) jonk => document



642
643
644
645
646
647
648
649
650
651
652
 
# File 'lib/docusign_rest/client.rb', line 642

def get_template(template_id, options = {})
  content_type = { 'Content-Type' => 'application/json' }
  content_type.merge(options[:headers]) if options[:headers]

  uri = build_uri("/accounts/#{acct_id}/templates/#{template_id}")

  http = initialize_net_http_ssl(uri)
  request = Net::HTTP::Get.new(uri.request_uri, headers(content_type))
  response = http.request(request)
  JSON.parse(response.body)
end

#get_template_roles(signers) ⇒ Object

Internal: takes in an array of hashes of signers and concatenates all the hashes with commas

embedded - Tells DocuSign if this is an embedded signer which determines

weather or not to deliver emails. Also lets us authenticate
them when they go to do embedded signing. Behind the scenes
this is setting the clientUserId value to the signer's email.

name - The name of the signer email - The email of the signer role_name - The role name of the signer (‘Attorney’, ‘Client’, etc.). tabs - Array of tab pairs grouped by type (Example type: ‘textTabs’)

{ textTabs: [ { tabLabel: "label", name: "name", value: "value" } ] }

NOTE: The 'tabs' option is NOT supported in 'v1' of the REST API

Returns a hash of users that need to be embedded in the template to create an envelope



215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
 
# File 'lib/docusign_rest/client.rb', line 215

def get_template_roles(signers)
  template_roles = []
  signers.each_with_index do |signer, index|
    template_role = {
      name:     signer[:name],
      email:    signer[:email],
      roleName: signer[:role_name],
      tabs: {
        textTabs:     get_signer_tabs(signer[:text_tabs]),
        checkboxTabs: get_signer_tabs(signer[:checkbox_tabs])
      }
    }

    if signer[:email_notification]
      template_role[:emailNotification] = signer[:email_notification]
    end

    template_role['clientUserId'] = (signer[:client_id] || signer[:email]).to_s if signer[:embedded] == true
    template_roles << template_role
  end
  template_roles
end

#get_templates ⇒ Object

Public: Retrieves a list of available templates

Example

client.get_templates()

Returns a list of the available templates.



1047
1048
1049
1050
1051
1052
1053
 
# File 'lib/docusign_rest/client.rb', line 1047

def get_templates
  uri = build_uri("/accounts/#{acct_id}/templates")

  http = initialize_net_http_ssl(uri)
  request = Net::HTTP::Get.new(uri.request_uri, headers({ 'Content-Type' => 'application/json' }))
  JSON.parse(http.request(request).body)
end

#get_token(account_id, email, password) ⇒ Object

Public: creates an OAuth2 authorization server token endpoint.

email - email of user authenticating password - password of user authenticating

Examples:

client = DocusignRest::Client.new
response = client.get_token('[email protected]', 'p@ssw0rd01')

Returns:

access_token - Access token information
scope - This should always be "api"
token_type - This should always be "bearer"



136
137
138
139
140
141
142
143
144
145
146
 
# File 'lib/docusign_rest/client.rb', line 136

def get_token(, email, password)
  content_type = { 'Content-Type' => 'application/x-www-form-urlencoded', 'Accept' => 'application/json' }
  uri = build_uri('/oauth2/token')

  request = Net::HTTP::Post.new(uri.request_uri, content_type)
  request.body = "grant_type=password&client_id=#{integrator_key}&username=#{email}&password=#{password}&scope=api"

  http = initialize_net_http_ssl(uri)
  response = http.request(request)
  JSON.parse(response.body)
end

#headers(user_defined_headers = {}) ⇒ Object

Internal: sets the default request headers allowing for user overrides via options from within other requests. Additionally injects the X-DocuSign-Authentication header to authorize the request.

Client can pass in header options to any given request: headers: => ‘some/value’, ‘Another-Key’ => ‘another/value’

Then we pass them on to this method to merge them with the other required headers

Example:

headers(options[:headers])

Returns a merged hash of headers overriding the default Accept header if the user passes in a new ‘Accept’ header key and adds any other user-defined headers along with the X-DocuSign-Authentication headers



60
61
62
63
64
65
66
67
68
 
# File 'lib/docusign_rest/client.rb', line 60

def headers(user_defined_headers={})
  default = {
    'Accept' => 'json' #this seems to get added automatically, so I can probably remove this
  }

  default.merge!(user_defined_headers) if user_defined_headers

  @docusign_authentication_headers.merge(default)
end

#initialize_net_http_multipart_post_request(uri, post_body, file_params, headers) ⇒ Object

Internal sets up the Net::HTTP request

uri - The fully qualified final URI post_body - The custom post body including the signers, etc file_params - Formatted hash of ios to merge into the post body headers - Allows for passing in custom headers

Returns a request object suitable for embedding in a request



503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
 
# File 'lib/docusign_rest/client.rb', line 503

def initialize_net_http_multipart_post_request(uri, post_body, file_params, headers)
  # Net::HTTP::Post::Multipart is from the multipart-post gem's lib/multipartable.rb
  #
  # path       - The fully qualified URI for the request
  # params     - A hash of params (including files for uploading and a
  #              customized request body)
  # headers={} - The fully merged, final request headers
  # boundary   - Optional: you can give the request a custom boundary
  #
  request = Net::HTTP::Post::Multipart.new(
    uri.request_uri,
    { post_body: post_body }.merge(file_params),
    headers
  )

  # DocuSign requires that we embed the document data in the body of the
  # JSON request directly so we need to call '.read' on the multipart-post
  # provided body_stream in order to serialize all the files into a
  # compatible JSON string.
  request.body = request.body_stream.read
  request
end

#initialize_net_http_ssl(uri) ⇒ Object

Internal: configures Net:HTTP with some default values that are required for every request to the DocuSign API

Returns a configured Net::HTTP object into which a request can be passed



90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
 
# File 'lib/docusign_rest/client.rb', line 90

def initialize_net_http_ssl(uri)
  http = Net::HTTP.new(uri.host, uri.port)

  http.use_ssl = uri.scheme == 'https'

  if defined?(Rails) && Rails.env.test?
    in_rails_test_env = true
  else
    in_rails_test_env = false
  end

  if http.use_ssl? && !in_rails_test_env
    if ca_file
      if File.exists?(ca_file)
        http.ca_file = ca_file
      else
        raise 'Certificate path not found.'
      end
    end

    # Explicitly verifies that the certificate matches the domain.
    # Requires that we use www when calling the production DocuSign API
    http.verify_mode = OpenSSL::SSL::VERIFY_PEER
    http.verify_depth = 5
  else
    http.verify_mode = OpenSSL::SSL::VERIFY_NONE
  end

  http
end

#move_envelope_to_folder(options = {}) ⇒ Object

Public moves the specified envelopes to the given folder

envelope_ids - IDs of the envelopes to be moved folder_id - ID of the folder to move the envelopes to headers - Optional hash of headers to merge into the existing

required headers for a multipart request.

Example

client.move_envelope_to_folder(
  envelope_ids: ["xxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxx"]
  folder_id: "xxxxx-2222xxxxx",
)

Returns the response.



933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
 
# File 'lib/docusign_rest/client.rb', line 933

def move_envelope_to_folder(options = {})
  content_type = { 'Content-Type' => 'application/json' }
  content_type.merge(options[:headers]) if options[:headers]

  post_body = {
    envelopeIds: options[:envelope_ids]
  }.to_json

  uri = build_uri("/accounts/#{acct_id}/folders/#{options[:folder_id]}")

  http = initialize_net_http_ssl(uri)
  request = Net::HTTP::Put.new(uri.request_uri, headers(content_type))
  request.body = post_body
  response = http.request(request)

  response
end

#search_folder_for_envelopes(options = {}) ⇒ Object

Public retrieves the envelope(s) from a specific folder based on search params.

Option Query Terms(none are required): query_params:

start_position: Integer The position of the folder items to return. This is used for repeated calls, when the number of envelopes returned is too much for one return (calls return 100 envelopes at a time). The default value is 0.
from_date:      date/Time Only return items on or after this date. If no value is provided, the default search is the previous 30 days.
to_date:        date/Time Only return items up to this date. If no value is provided, the default search is to the current date.
search_text:    String   The search text used to search the items of the envelope. The search looks at recipient names and emails, envelope custom fields, sender name, and subject.
status:         Status  The current status of the envelope. If no value is provided, the default search is all/any status.
owner_name:     username  The name of the folder owner.
owner_email:    email The email of the folder owner.

Example

client.search_folder_for_envelopes(
  folder_id: xxxxx-2222xxxxx,
  query_params: {
    search_text: "John Appleseed",
    from_date: '7-1-2011+11:00:00+AM',
    to_date: '7-1-2011+11:00:00+AM',
    status: "completed"
  }
)



976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
 
# File 'lib/docusign_rest/client.rb', line 976

def search_folder_for_envelopes(options={})
  content_type = { 'Content-Type' => 'application/json' }
  content_type.merge(options[:headers]) if options[:headers]

  q ||= []
  options[:query_params].each do |key, val|
    q << "#{key}=#{val}"
  end

  uri = build_uri("/accounts/#{@acct_id}/folders/#{options[:folder_id]}/?#{q.join('&')}")

  http = initialize_net_http_ssl(uri)
  request = Net::HTTP::Get.new(uri.request_uri, headers(content_type))
  response = http.request(request)
  JSON.parse(response.body)
end