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.



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
41
42
43
44
45
 
# File 'lib/docusign_rest/client.rb', line 12

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 = 

  #initialize the log cache
  @previous_call_log = []
end

Instance Attribute Details

#acct_id ⇒ Object

Returns the value of attribute acct_id.



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

def acct_id
  @acct_id
end

#docusign_authentication_headers ⇒ Object

Returns the value of attribute docusign_authentication_headers.



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

def docusign_authentication_headers
  @docusign_authentication_headers
end

#previous_call_log ⇒ Object

Returns the value of attribute previous_call_log.



10
11
12
 
# File 'lib/docusign_rest/client.rb', line 10

def previous_call_log
  @previous_call_log
end

Instance Method Details

#add_envelope_certified_deliveries(options = {}) ⇒ Object

Public adds the certified delivery recipients (Need to View) for a given envelope

envelope_id - ID of the envelope for which you want to retrieve the

signer info

headers - optional hash of headers to merge into the existing

required headers for a multipart request.

certified_deliveries - A required hash of all the certified delivery recipients

that need to be added to the envelope

# The response returns the success or failure of each recipient being added to the envelope and the envelope ID



1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
 
# File 'lib/docusign_rest/client.rb', line 1060

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

  post_body = {
    certifiedDeliveries: get_certified_deliveries(options[:certified_deliveries]),
  }.to_json

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

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

#add_envelope_document(options = {}) ⇒ Object

Public adds a document to a given envelope See docs.docusign.com/esign/restapi/Envelopes/EnvelopeDocuments/update/

envelope_id - ID of the envelope from which the doc will be added document_id - ID of the document to add file_path - Local or remote path to file content_type - optional content type for file. Defaults to application/pdf. file_name - optional name for file. Defaults to basename of file_path. file_extension - optional extension for file. Defaults to extname of file_name. file_io - Optional: an opened I/O stream of data (if you don’t

want to read from a file)

The response only returns a success or failure.



1683
1684
1685
1686
1687
1688
1689
1690
1691
1692
1693
1694
1695
1696
1697
1698
1699
1700
1701
1702
1703
1704
1705
1706
 
# File 'lib/docusign_rest/client.rb', line 1683

def add_envelope_document(options={})
  options[:content_type] ||= 'application/pdf'
  options[:file_name] ||= File.basename(options[:file_path])
  options[:file_extension] ||= File.extname(options[:file_name])[1..-1]

  headers = {
    'Content-Type' => options[:content_type],
    'Content-Disposition' => "file; filename=\"#{options[:file_name]}\"; documentid=#{options[:document_id]}; fileExtension=\"#{options[:file_extension]}\""
  }

  uri = build_uri("/accounts/#{@acct_id}/envelopes/#{options[:envelope_id]}/documents/#{options[:document_id]}")
  post_body = if options[:file_io].present?
    options[:file_io].read
  else
    open(options[:file_path]).read
  end

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

#add_envelope_recipients(options = {}) ⇒ Object

Public: Add recipients to envelope



1954
1955
1956
1957
1958
1959
1960
1961
1962
1963
1964
1965
1966
1967
1968
1969
1970
 
# File 'lib/docusign_rest/client.rb', line 1954

def add_envelope_recipients(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]}/recipients?resend_envelope=true")

  post_body = {
    signers: get_signers(options[:signers])
  }.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

#add_envelope_signers(options = {}) ⇒ Object

Public adds signers to a given envelope Seedocs.docusign.com/esign/restapi/Envelopes/EnvelopeRecipients/update/

envelope_id - ID of the envelope to which the recipient will be added signers - Array of hashes

See https://docs.docusign.com/esign/restapi/Envelopes/EnvelopeRecipients/update/#definitions

TODO: This could be made more general as an add_envelope_recipient method to handle recipient types other than Signer See: docs.docusign.com/esign/restapi/Envelopes/EnvelopeRecipients/update/#examples



1718
1719
1720
1721
1722
1723
1724
1725
1726
1727
1728
1729
1730
1731
1732
 
# File 'lib/docusign_rest/client.rb', line 1718

def add_envelope_signers(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]}/recipients")
  post_body = { signers: options[:signers] }.to_json

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

#add_recipient_tabs(options = {}) ⇒ Object

Public adds recipient tabs to a given envelope See docs.docusign.com/esign/restapi/Envelopes/EnvelopeRecipients/update/

envelope_id - ID of the envelope from which the doc will be added recipient - ID of the recipient to add tabs to tabs - hash of tab (see example below) {

signHereTabs: [
  {
    anchorString: '/s1/',
    anchorXOffset: '5',
    anchorYOffset: '8',
    anchorIgnoreIfNotPresent: 'true',
    documentId: '1',
    pageNumber: '1',
    recipientId: '1'
  }
],
initialHereTabs: [
  {
    anchorString: '/i1/',
    anchorXOffset: '5',
    anchorYOffset: '8',
    anchorIgnoreIfNotPresent: 'true',
    documentId: '1',
    pageNumber: '1',
    recipientId: '1'
  }
]

}

The response returns the success or failure of each document being added to the envelope and the envelope ID. Failed operations on array elements will add the “errorDetails” structure containing an error code and message. If “errorDetails” is null, then the operation was successful for that item.



1769
1770
1771
1772
1773
1774
1775
1776
1777
1778
1779
1780
1781
1782
1783
1784
1785
1786
1787
1788
1789
1790
1791
1792
1793
1794
1795
1796
1797
1798
1799
1800
1801
1802
1803
1804
1805
1806
1807
 
# File 'lib/docusign_rest/client.rb', line 1769

def add_recipient_tabs(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]}/recipients/#{options[:recipient_id]}/tabs")
  tabs = options[:tabs]
  index = options[:recipient_id] -  1

  post_body = {
    approveTabs:          nil,
    checkboxTabs:         nil,
    companyTabs:          nil,
    dateSignedTabs:       get_tabs(tabs[:date_signed_tabs], options, index),
    dateTabs:             nil,
    declineTabs:          nil,
    emailTabs:            nil,
    envelopeIdTabs:       nil,
    fullNameTabs:         nil,
    listTabs:             nil,
    noteTabs:             nil,
    numberTabs:           nil,
    radioGroupTabs:       nil,
    initialHereTabs:      get_tabs(tabs[:initial_here_tabs], options.merge!(initial_here_tab: true), index),
    signHereTabs:         get_tabs(tabs[:sign_here_tabs], options.merge!(sign_here_tab: true), index),
    signerAttachmentTabs: nil,
    ssnTabs:              nil,
    textTabs:             get_tabs(tabs[:text_tabs], options, index),
    titleTabs:            nil,
    zipTabs:              nil
  }.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)
  generate_log(request, response, uri)
  JSON.parse(response.body)
end

#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



86
87
88
 
# File 'lib/docusign_rest/client.rb', line 86

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

#camelize(str) ⇒ Object

Generic implementation to avoid having to pull in Rails dependencies



466
467
468
 
# File 'lib/docusign_rest/client.rb', line 466

def camelize(str)
  str.gsub(/_([a-z])/) { $1.upcase }
end

#camelize_keys(hash) ⇒ Object

Public: Translate ruby oriented keys to camel cased keys recursively through the hash received

The method expects symbol parameters in ruby form “:access_code” and translates them to camel cased “accessCode”

example [‘12345’, email_notification: {email_body: ‘abcdef’}] -> [‘12345’, ‘emailNotification’: {‘emailBody’: ‘abcdef’}]



456
457
458
459
460
461
462
 
# File 'lib/docusign_rest/client.rb', line 456

def camelize_keys(hash)
  new_hash={}
  hash.each do |k,v|
    new_hash[camelize(k.to_s)] = (v.is_a?(Hash) ? camelize_keys(v) : v)
  end
  new_hash
end

#convert_hash_keys(value) ⇒ Object

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



1501
1502
1503
1504
1505
1506
1507
1508
1509
1510
 
# File 'lib/docusign_rest/client.rb', line 1501

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



1483
1484
1485
1486
1487
1488
1489
1490
1491
1492
1493
1494
1495
1496
1497
 
# File 'lib/docusign_rest/client.rb', line 1483

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

#create_envelope_from_composite_template(options = {}) ⇒ Object

Public: create an envelope for delivery from a composite template

headers - Optional hash of headers to merge into the existing

required headers for a POST request.

status - Options include: ‘sent’, or ‘created’ 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 files - Sets documents to be used instead of inline or server templates signers - See get_template_roles/get_inline_signers for a list

of options to pass.

headers - Optional hash of headers to merge into the existing

required headers for a multipart request.

server_template_ids - Array of ids for templates uploaded to DocuSign. Templates

will be added in the order they appear in the array.

Returns a JSON parsed response body containing the envelope’s:

envelopeId - autogenerated ID provided by Docusign
uri - the URI where the template is located on the DocuSign servers
statusDateTime - The date/time the envelope was created
status         - Sent, created, or voided



954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
 
# File 'lib/docusign_rest/client.rb', line 954

def create_envelope_from_composite_template(options={})
  file_params = {}

  if options[:files]
    ios = create_file_ios(options[:files])
    file_params = create_file_params(ios)
  end

  post_hash = {
    emailBlurb:        "#{options[:email][:body] if options[:email]}",
    emailSubject:      "#{options[:email][:subject] if options[:email]}",
    status:             options[:status],
    brandId:            options[:brand_id],
    eventNotification:  get_event_notification(options[:event_notification]),
    allowReassign:      options[:allow_reassign],
    compositeTemplates: get_composite_template(options[:server_template_ids], options[:signers], options[:files])
  }

  post_body = post_hash.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)
  generate_log(request, response, uri)
  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 - (Optional) short subject line for the email email - (Optional) custom text that will be injected into the

DocuSign generated email

email_settings - (Optional) array of emails to BCC. email_settings - (Optional) override the default reply to email for the account. email_settings - (Optional) override the default reply to name for the account. 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.

carbon_copies - An array of hashes that includes users names and email who

should receive a copy of the document once it is complete.

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

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

customFields - (Optional) A hash of listCustomFields and textCustomFields.

Each contains an array of corresponding customField hashes.
For details, please see: http://bit.ly/1FnmRJx

headers - Allows a client to pass in some headers wet_sign - (Optional) If true, the signer is allowed to print the

document and sign it on paper. False if not defined.

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



765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
 
# File 'lib/docusign_rest/client.rb', line 765

def create_envelope_from_document(options={})
  ios = create_file_ios(options[:files])
  file_params = create_file_params(ios)
  recipients = if options[:certified_deliveries].nil? || options[:certified_deliveries].empty?
                 { signers: get_signers(options[:signers]) }
               else
                 { certifiedDeliveries: get_signers(options[:certified_deliveries]) }
               end


  post_hash = {
    emailBlurb:   "#{options[:email][:body] if options[:email]}",
    emailSubject: "#{options[:email][:subject] if options[:email]}",
    emailSettings: get_email_settings(options[:email_settings]),
    documents: get_documents(ios),
    recipients: {
      signers: get_signers(options[:signers]),
      carbonCopies: get_carbon_copies(options[:carbon_copies],options[:signers].size)
    },
    eventNotification: get_event_notification(options[:event_notification]),
    status: "#{options[:status]}",
    customFields: options[:custom_fields]
  }
  post_hash[:enableWetSign] = options[:wet_sign] if options.has_key? :wet_sign
  post_body = post_hash.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)
  generate_log(request, response, uri)
  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



902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
 
# File 'lib/docusign_rest/client.rb', line 902

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],
    enableWetSign:      options[:wet_sign],
    brandId:            options[:brand_id],
    eventNotification:  get_event_notification(options[:event_notification]),
    templateRoles:      get_template_roles(options[:signers]),
    customFields:       options[:custom_fields],
    allowReassign:      options[:allow_reassign]
  }.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)
  generate_log(request, response, uri)
  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



563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
 
# File 'lib/docusign_rest/client.rb', line 563

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



608
609
610
611
612
613
614
615
 
# File 'lib/docusign_rest/client.rb', line 608

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_signing_group(options = {}) ⇒ Object

Public method - Creates Signing group group_name: The display name for the signing group. This can be a maximum of 100 characters. users: An array of group members for the signing group. (see example below)

It is composed of two elements:
name – The name for the group member. This can be a maximum of 100 characters.
email – The email address for the group member. This can be a maximum of 100 characters.

[

{name: 'test1', email: '[email protected]'}
{name: 'test2', email: '[email protected]'}

]

The response returns a success or failure with any error messages. For successes DocuSign generates a signingGroupId for each group, which is included in the response. The response also includes information about when the group was created and modified, including the account user that created and modified the group.



1825
1826
1827
1828
1829
1830
1831
1832
1833
1834
1835
1836
1837
1838
1839
1840
1841
1842
1843
1844
1845
1846
1847
1848
1849
1850
1851
1852
1853
1854
1855
1856
1857
1858
1859
 
# File 'lib/docusign_rest/client.rb', line 1825

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

  group_users = []
  if options[:users]
    options[:users].each do |user|
      group_users << {
        userName: user[:name],
        email: user[:email]
      }
    end
  end

  post_body = {
      groups: [
        {
          groupName: options[:group_name],
          groupType: 'sharedSigningGroup',
          users: group_users
        }
      ]
    }.to_json

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

  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_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



832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
 
# File 'lib/docusign_rest/client.rb', line 832

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

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

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



1514
1515
1516
1517
1518
1519
1520
1521
1522
1523
1524
1525
1526
1527
 
# File 'lib/docusign_rest/client.rb', line 1514

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)
  generate_log(request, response, uri)
  json = response.body
  json = '{}' if json.nil? || json == ''
  JSON.parse(json)
end

#delete_envelope_document(options = {}) ⇒ Object

Public deletes a document for a given envelope See docs.docusign.com/esign/restapi/Envelopes/EnvelopeDocuments/delete/

envelope_id - ID of the envelope from which the doc will be retrieved document_id - ID of the document to delete

Returns the success or failure of each document being added to the envelope and the envelope ID. Failed operations on array elements will add the “errorDetails” structure containing an error code and message. If “errorDetails” is null, then the operation was successful for that item.



1650
1651
1652
1653
1654
1655
1656
1657
1658
1659
1660
1661
1662
1663
1664
1665
1666
1667
1668
 
# File 'lib/docusign_rest/client.rb', line 1650

def delete_envelope_document(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")
  post_body = {
    documents: [
      { documentId: options[:document_id] }
    ]
  }.to_json

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

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

#delete_envelope_recipient(options = {}) ⇒ Object

Public deletes a recipient for a given envelope

envelope_id - ID of the envelope for which you want to retrieve the

signer info

recipient_id - ID of the recipient to delete

Returns a hash of recipients with an error code for any recipients that were not successfully deleted.



1596
1597
1598
1599
1600
1601
1602
1603
1604
1605
1606
1607
1608
1609
1610
1611
1612
 
# File 'lib/docusign_rest/client.rb', line 1596

def delete_envelope_recipient(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]}/recipients")
  post_body = "{
    \"signers\" : [{\"recipientId\" : \"#{options[:recipient_id]}\"}]
   }"

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

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

#delete_signing_groups(options = {}) ⇒ Object

Public method - deletes a signing group See docs.docusign.com/esign/restapi/SigningGroups/SigningGroups/delete/

signingGroupId - ID of the signing group to delete

Returns the success or failure of each group being deleted. Failed operations on array elements will add the “errorDetails” structure containing an error code and message. If “errorDetails” is null, then the operation was successful for that item.



1869
1870
1871
1872
1873
1874
1875
1876
1877
1878
1879
1880
1881
1882
1883
1884
1885
1886
1887
 
# File 'lib/docusign_rest/client.rb', line 1869

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

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

  groups = options[:groups]
  groups.each{|h| h[:signingGroupId] = h.delete(:signing_group_id) if h.key?(:signing_group_id)}
  post_body = {
    groups: groups
  }.to_json

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

  response = http.request(request)
  JSON.parse(response.body)
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



197
198
199
200
201
202
203
204
205
206
 
# File 'lib/docusign_rest/client.rb', line 197

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

  acct_id
end

#get_carbon_copies(options, signer_count) ⇒ Object

Internal: people to be Carbon Copied on the document that is created docs.docusign.com/esign/restapi/Envelopes/Envelopes/create/

Expecting options to be an array of hashes, with each hash representing a person to carbon copy

email - The email of the recipient to be copied on the document name - The name of the recipient signer_count - Used to generate required attributes recipientId and routingOrder which must be unique in the document



439
440
441
442
443
444
445
446
447
448
 
# File 'lib/docusign_rest/client.rb', line 439

def get_carbon_copies(options, signer_count)
  copies = []
    (options || []).each do |cc|
      signer_count += 1
      raise "Missing required data [:email, :name]" unless (cc[:email] && cc[:name])
      cc.merge!(recipient_id: signer_count, routing_order: signer_count)
      copies << camelize_keys(cc)
    end
  copies
end

#get_certified_deliveries(certified_deliveries) ⇒ Object

Internal: takes an array of hashes of certified deliveries

email - The recipient email name - The recipient name recipient_id - The recipient’s id embedded - Tells DocuSign if this is an embedded recipient which

determines whether or not to deliver emails.



477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
 
# File 'lib/docusign_rest/client.rb', line 477

def get_certified_deliveries(certified_deliveries)
  doc_certified_deliveries = []

  certified_deliveries.each do |certified_delivery|
    doc_certified_delivery = {
      email:        certified_delivery[:email],
      name:         certified_delivery[:name],
      recipientId:  certified_delivery[:recipient_id]
    }

    if certified_delivery[:embedded]
      doc_certified_delivery[:clientUserId] = certified_delivery[:client_id] || certified_delivery[:email]
    end

    doc_certified_deliveries << doc_certified_delivery
  end
  doc_certified_deliveries
end

#get_combined_document_from_envelope(options = {}) ⇒ Object

Public retrieves a PDF containing the combined content of all documents and the certificate for the given envelope.

envelope_id - ID of the envelope from which the doc will be retrieved 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.

params - Optional params; for example, certificate: true

Example

client.get_combined_document_from_envelope(
  envelope_id: @envelope_response['envelopeId'],
  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.



1344
1345
1346
1347
1348
1349
1350
1351
1352
1353
1354
1355
1356
1357
1358
1359
1360
1361
1362
1363
1364
1365
 
# File 'lib/docusign_rest/client.rb', line 1344

def get_combined_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/combined")
  uri.query = URI.encode_www_form(options[:params]) if options[:params]

  http = initialize_net_http_ssl(uri)
  request = Net::HTTP::Get.new(uri.request_uri, headers(content_type))
  response = http.request(request)
  generate_log(request, response, uri)
  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_composite_template(server_template_ids, signers, files) ⇒ Object

Internal: takes in an array of server template ids and an array of the signers and sets up the composite template

Takes an optional array of files, which consist of documents to be used instead of templates

Returns an array of server template hashes



637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
 
# File 'lib/docusign_rest/client.rb', line 637

def get_composite_template(server_template_ids, signers, files)
  composite_array = []
  server_template_ids.each_with_index do |template_id, idx|
    server_template_hash = {
        sequence: (idx+1).to_s,
        templateId: template_id,
        templateRoles: get_template_roles(signers),
    }
    templates_hash = {
      serverTemplates: [server_template_hash],
      inlineTemplates: get_inline_signers(signers, (idx+1).to_s)
    }
    if files
      document_hash = {
          documentId: (idx+1).to_s,
          name: "#{files[idx][:name] if files[idx]}"
      }
      templates_hash[:document] = document_hash
    end
    composite_array << templates_hash
  end
  composite_array
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)



1147
1148
1149
1150
1151
1152
1153
1154
1155
1156
1157
1158
1159
1160
1161
1162
1163
1164
1165
1166
 
# File 'lib/docusign_rest/client.rb', line 1147

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)
  generate_log(request, response, uri)
  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.



1283
1284
1285
1286
1287
1288
1289
1290
1291
1292
1293
1294
1295
1296
1297
1298
1299
1300
1301
1302
1303
 
# File 'lib/docusign_rest/client.rb', line 1283

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)
  generate_log(request, response, uri)
  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_document_tabs(options) ⇒ Object

Public fetches custom fields for a document

options - ID of the envelope which you want to send options - ID of the envelope which you want to send

Returns the custom fields Hash.



993
994
995
996
997
998
999
1000
1001
1002
 
# File 'lib/docusign_rest/client.rb', line 993

def get_document_tabs(options)
  content_type = { 'Content-Type' => 'application/json' }
  uri = build_uri("/accounts/#{acct_id}/envelopes/#{options[:envelope_id]}/documents/#{options[:document_id]}/tabs")

  http = initialize_net_http_ssl(uri)
  request = Net::HTTP::Get.new(uri.request_uri, headers(content_type))
  response = http.request(request)
  generate_log(request, response, uri)
  JSON.parse(response.body)
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



622
623
624
625
626
627
628
629
 
# File 'lib/docusign_rest/client.rb', line 622

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



1311
1312
1313
1314
1315
1316
1317
1318
1319
1320
1321
1322
 
# File 'lib/docusign_rest/client.rb', line 1311

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)
  generate_log(request, response, uri)
  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.



1576
1577
1578
1579
1580
1581
1582
1583
1584
1585
 
# File 'lib/docusign_rest/client.rb', line 1576

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

#get_envelope_audit_events(options = {}) ⇒ Object

Public returns a hash of audit events for a given envelope

envelope_id - ID of the envelope to get audit events from

Example client.get_envelope_audit_events(

envelope_id: "xxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxx"

) Returns a hash of the events that have happened to the envelope.



1412
1413
1414
1415
1416
1417
1418
1419
1420
1421
1422
1423
 
# File 'lib/docusign_rest/client.rb', line 1412

def get_envelope_audit_events(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]}/audit_events")

  http = initialize_net_http_ssl(uri)
  request = Net::HTTP::Get.new(uri.request_uri, headers(content_type))
  response = http.request(request)
  generate_log(request, response, uri)
  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 retrieve 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



1180
1181
1182
1183
1184
1185
1186
1187
1188
1189
1190
1191
1192
1193
 
# File 'lib/docusign_rest/client.rb', line 1180

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)
  generate_log(request, response, uri)
  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



1199
1200
1201
1202
1203
1204
1205
1206
1207
1208
1209
1210
 
# File 'lib/docusign_rest/client.rb', line 1199

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)
  generate_log(request, response, uri)
  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'

envelope_ids - Comma joined list of envelope_ids which you want to query.

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

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



1228
1229
1230
1231
1232
1233
1234
1235
1236
1237
1238
1239
1240
1241
 
# File 'lib/docusign_rest/client.rb', line 1228

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, :envelope_ids, :status)
  # Note that Hash#to_query is an ActiveSupport monkeypatch
  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)
  generate_log(request, response, uri)
  JSON.parse(response.body)
end

#get_event_notification(event_notification) ⇒ Object

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



288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
 
# File 'lib/docusign_rest/client.rb', line 288

def get_event_notification(event_notification)
  return {} unless event_notification
  {
    useSoapInterface:          event_notification[:use_soap_interface] || false,
    includeCertificateWithSoap: 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,
    'recipientEvents' => Array(event_notification[:recipient_events]).map do |recipient_event|
      {
        includeDocuments:         recipient_event[:include_documents] || false,
        recipientEventStatusCode: recipient_event[:recipient_event_status_code]
      }
    end
  }
end

#get_folder_list(options = {}) ⇒ Object

Public retrieves folder information. Helpful to use before client.search_folder_for_envelopes



1426
1427
1428
1429
1430
1431
1432
1433
1434
1435
1436
1437
 
# File 'lib/docusign_rest/client.rb', line 1426

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

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

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

#get_inline_signers(signers, sequence) ⇒ Object

Internal: takes signer info and the inline template sequence number and sets up the inline template

Returns an array of signers



666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
 
# File 'lib/docusign_rest/client.rb', line 666

def get_inline_signers(signers, sequence)
  signers_array = []
  signers.each do |signer|
    signers_hash = {
      email: signer[:email],
      name: signer[:name],
      recipientId: signer[:recipient_id],
      roleName: signer[:role_name],
      clientUserId: signer[:client_id] || signer[:email],
      requireSignOnPaper: signer[:require_sign_on_paper] || false,
      tabs: {
        textTabs:       get_signer_tabs(signer[:text_tabs]),
        radioGroupTabs: get_radio_signer_tabs(signer[:radio_group_tabs]),
        checkboxTabs:   get_signer_tabs(signer[:checkbox_tabs]),
        numberTabs:     get_signer_tabs(signer[:number_tabs]),
        fullNameTabs:   get_signer_tabs(signer[:fullname_tabs]),
        dateTabs:       get_signer_tabs(signer[:date_tabs]),
        signHereTabs:   get_sign_here_tabs(signer[:sign_here_tabs])
      }
    }
    signers_array << signers_hash
  end
  template_hash = {sequence: sequence, recipients: { signers: signers_array }}
  [template_hash]
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



176
177
178
179
180
181
182
183
 
# File 'lib/docusign_rest/client.rb', line 176

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

#get_page_image(options = {}) ⇒ Object

Public retrieves a png of a page of a document in an envelope

envelope_id - ID of the envelope from which the doc will be retrieved document_id - ID of the document to retrieve page_number - page number to retrieve

Returns the png as a bytestream



1250
1251
1252
1253
1254
1255
1256
1257
1258
1259
1260
1261
1262
 
# File 'lib/docusign_rest/client.rb', line 1250

def get_page_image(options={})
  envelope_id = options[:envelope_id]
  document_id = options[:document_id]
  page_number = options[:page_number]

  uri = build_uri("/accounts/#{acct_id}/envelopes/#{envelope_id}/documents/#{document_id}/pages/#{page_number}/page_image")

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

#get_radio_signer_tabs(tabs) ⇒ Object 



277
278
279
280
281
282
283
284
285
 
# File 'lib/docusign_rest/client.rb', line 277

def get_radio_signer_tabs(tabs)
  Array(tabs).map do |tab|
    {
      'documentId' => tab[:document_id],
      'groupName' => tab[:group_name],
      'radios' => tab[:radios],
    }
  end
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



1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
 
# File 'lib/docusign_rest/client.rb', line 1034

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)
  generate_log(request, response, uri)
  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)



1091
1092
1093
1094
1095
1096
1097
1098
1099
1100
1101
1102
1103
1104
1105
1106
1107
1108
1109
1110
1111
1112
1113
 
# File 'lib/docusign_rest/client.rb', line 1091

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

#get_sender_view(options = {}) ⇒ Object

Public returns the URL for embedded sending

envelope_id - the ID of the envelope you wish to use return_url - the URL you want the user to be directed to after he or she

closes the view

headers - optional hash of headers to merge into the existing

required headers for a multipart request.

Returns the URL string for embedded sending



1124
1125
1126
1127
1128
1129
1130
1131
1132
1133
1134
1135
1136
1137
1138
 
# File 'lib/docusign_rest/client.rb', line 1124

def get_sender_view(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]}/views/sender")

  http = initialize_net_http_ssl(uri)

  request = Net::HTTP::Post.new(uri.request_uri, headers(content_type))
  request.body = { returnUrl: options[:return_url] }.to_json

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

#get_sign_here_tabs(tabs) ⇒ Object 



251
252
253
254
255
256
257
258
259
260
261
 
# File 'lib/docusign_rest/client.rb', line 251

def get_sign_here_tabs(tabs)
  Array(tabs).map do |tab|
    {
      documentId: tab[:document_id],
      recipientId: tab[:recipient_id],
      anchorString: tab[:anchor_string],
      anchorXOffset: tab[:anchorXOffset],
      anchorYOffset: tab[:anchorYOffset]
    }
  end
end

#get_signer_tabs(tabs) ⇒ Object

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



264
265
266
267
268
269
270
271
272
273
274
275
 
# File 'lib/docusign_rest/client.rb', line 264

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],
      'locked' => tab[:locked]
    }
  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 whether 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



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
369
370
371
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
419
420
421
422
423
424
425
426
427
 
# File 'lib/docusign_rest/client.rb', line 341

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

  signers.each_with_index do |signer, index|
    doc_signer = {
      accessCode:                            '',
      addAccessCodeToEmail:                  false,
      customFields:                          signer[:custom_fields],
      idCheckConfigurationName:              signer[:id_check_configuration_name],
      idCheckInformationInput:               nil,
      inheritEmailNotificationConfiguration: false,
      note:                                  signer[:note],
      phoneAuthentication:                   nil,
      recipientAttachment:                   nil,
      requireIdLookup:                       signer[:require_id_lookup],
      requireSignOnPaper:                    signer[:require_sign_on_paper] || false,
      roleName:                              signer[:role_name],
      routingOrder:                          signer[:routing_order] || index + 1,
      socialAuthentications:                 nil
    }

    recipient_id = signer[:recipient_id] || index + 1
    doc_signer[:recipientId] = recipient_id
    doc_signer[:clientUserId] = recipient_id if signer[:embedded_signing]

    if signer[:id_check_information_input]
      doc_signer[:idCheckInformationInput] =
        get_id_check_information_input(signer[:id_check_information_input])
    end

    if signer[:phone_authentication]
      doc_signer[:phoneAuthentication] =
        get_phone_authentication(signer[:phone_authentication])
    end

    if signer[:signing_group_id]
      doc_signer[:signingGroupId] = signer[:signing_group_id]
    else
      doc_signer[:email] = signer[:email]
      doc_signer[:name] = signer[:name]
    end

    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:           get_tabs(signer[:number_tabs], options, index),
      radioGroupTabs:       get_tabs(signer[:radio_group_tabs], options, index),
      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_signing_groups ⇒ Object

Public: Retrieves a list of available signing groups



1920
1921
1922
1923
1924
1925
1926
 
# File 'lib/docusign_rest/client.rb', line 1920

def get_signing_groups
  uri = build_uri("/accounts/#{@acct_id}/signing_groups")

  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_tabs(tabs, options, index) ⇒ Object

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



497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
 
# File 'lib/docusign_rest/client.rb', line 497

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]   = tab[:conditional_parent_label] if tab.key?(:conditional_parent_label)
    tab_hash[:conditionalParentValue]   = tab[:conditional_parent_value] if tab.key?(:conditional_parent_value)
    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[:scale_value] || 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]   = tab[:optional] || false
    tab_hash[:tabLabel]   = tab[:label] || 'Signature 1'
    tab_hash[:width]      = tab[:width] if tab[:width]
    tab_hash[:height]     = tab[:height] if tab[:height]
    tab_hash[:value]      = tab[:value] if tab[:value]
    tab_hash[:fontSize]   = tab[:font_size] if tab[:font_size]
    tab_hash[:fontColor]  = tab[:font_color] if tab[:font_color]
    tab_hash[:bold]       = tab[:bold] if tab[:bold]
    tab_hash[:italic]     = tab[:italic] if tab[:italic]
    tab_hash[:underline]  = tab[:underline] if tab[:underline]
    tab_hash[:selected]   = tab[:selected] if tab[:selected]

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

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

    tab_hash[:groupName] = tab[:group_name] if tab.key?(:group_name)
    tab_hash[:radios] = get_tabs(tab[:radios], options, index) if tab.key?(:radios)

    tab_hash[:validationMessage] = tab[:validation_message] if tab[:validation_message]
    tab_hash[:validationPattern] = tab[:validation_pattern] if tab[:validation_pattern]

    tab_array << tab_hash
  end
  tab_array
end

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

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



866
867
868
869
870
871
872
873
874
875
876
877
 
# File 'lib/docusign_rest/client.rb', line 866

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)
  generate_log(request, response, uri)
  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

whether 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" } ] }

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



224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
 
# File 'lib/docusign_rest/client.rb', line 224

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]),
        numberTabs:   get_signer_tabs(signer[:number_tabs]),
        radioGroupTabs: get_radio_signer_tabs(signer[:radio_group_tabs]),
        fullNameTabs: get_signer_tabs(signer[:fullname_tabs]),
        dateTabs:     get_signer_tabs(signer[:date_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(options = {}) ⇒ Object

Public: Retrieves a list of available templates

params: Can contain a folder

Example

client.get_templates()

or

client.get_templates(params: {folder: "somefolder"})

Returns a list of the available templates.



1543
1544
1545
1546
1547
1548
1549
1550
1551
1552
 
# File 'lib/docusign_rest/client.rb', line 1543

def get_templates(options={})
  uri = build_uri("/accounts/#{acct_id}/templates")
  uri.query = URI.encode_www_form(options[:params]) if options[:params]

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

#get_templates_in_envelope(envelope_id) ⇒ Object

Public: Retrieves a list of templates used in an envelope

Returns templateId, name and uri for each template found.

envelope_id - DS id of envelope with templates.



1560
1561
1562
1563
1564
1565
1566
1567
1568
 
# File 'lib/docusign_rest/client.rb', line 1560

def get_templates_in_envelope(envelope_id)
  uri = build_uri("/accounts/#{acct_id}/envelopes/#{envelope_id}/templates")

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

#get_token(integrator_key, 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(integrator_key, '[email protected]', 'p@ssw0rd01')

Returns:

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



144
145
146
147
148
149
150
151
152
153
154
155
 
# File 'lib/docusign_rest/client.rb', line 144

def get_token(integrator_key, 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)
  generate_log(request, response, uri)
  JSON.parse(response.body)
end

#get_users_list(options = {}) ⇒ Object

Public method - get list of users See developers.docusign.com/esign-rest-api/reference/Users

Returns a list of users



1976
1977
1978
1979
1980
1981
1982
1983
1984
1985
1986
1987
1988
1989
 
# File 'lib/docusign_rest/client.rb', line 1976

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

  uri = build_uri("/accounts/#{@acct_id}/users?additional_info=true")

  request = Net::HTTP::Get.new(uri.request_uri, headers(options[:headers]))
  http = initialize_net_http_ssl(uri)
  response = http.request(request)
  generate_log(request, response, uri)

  parsed_response = JSON.parse(response.body)
  (parsed_response || {}).fetch("users", [])
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



65
66
67
68
69
70
71
72
73
 
# File 'lib/docusign_rest/client.rb', line 65

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



701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
 
# File 'lib/docusign_rest/client.rb', line 701

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
  #

  headers = headers.dup.merge(parts: {post_body: {'Content-Type' => 'application/json'}})

  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



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
120
121
122
123
124
125
126
127
 
# File 'lib/docusign_rest/client.rb', line 95

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.open_timeout = open_timeout
  http.read_timeout = read_timeout

  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.



1383
1384
1385
1386
1387
1388
1389
1390
1391
1392
1393
1394
1395
1396
1397
1398
1399
 
# File 'lib/docusign_rest/client.rb', line 1383

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)
  generate_log(request, response, uri)
  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"
  }
)



1463
1464
1465
1466
1467
1468
1469
1470
1471
1472
1473
1474
1475
1476
1477
1478
1479
 
# File 'lib/docusign_rest/client.rb', line 1463

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

#send_envelope(envelope_id) ⇒ Object

Public marks an envelope as sent

envelope_id - ID of the envelope which you want to send

Returns the response (success or failure).



1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
 
# File 'lib/docusign_rest/client.rb', line 1009

def send_envelope(envelope_id)
  content_type = { 'Content-Type' => 'application/json' }

  post_body = {
    status: 'sent'
  }.to_json

  uri = build_uri("/accounts/#{acct_id}/envelopes/#{envelope_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)

  JSON.parse(response.body)
end

#update_envelope_recipients(options = {}) ⇒ Object

Public: Update envelope recipients



1929
1930
1931
1932
1933
1934
1935
1936
1937
1938
1939
1940
1941
1942
1943
1944
1945
1946
1947
1948
1949
1950
1951
 
# File 'lib/docusign_rest/client.rb', line 1929

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

  resend = options[:resend].present?
  uri = build_uri("/accounts/#{@acct_id}/envelopes/#{options[:envelope_id]}/recipients?resend_envelope=#{resend}")

  signers = options[:signers]
  signers.each do |signer|
   signer[:recipientId] = signer.delete(:recipient_id) if signer.key?(:recipient_id)
   signer[:clientUserId] = signer.delete(:client_user_id) if signer.key?(:client_user_id)
  end
  post_body = {
    signers: signers
  }.to_json

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

#update_signing_group_users(options = {}) ⇒ Object

Public method - updates signing group users See docs.docusign.com/esign/restapi/SigningGroups/SigningGroupUsers/update/

signingGroupId - ID of the signing group to update

Returns the success or failure of each user being updated. Failed operations on array elements will add the “errorDetails” structure containing an error code and message. If “errorDetails” is null, then the operation was successful for that item.



1897
1898
1899
1900
1901
1902
1903
1904
1905
1906
1907
1908
1909
1910
1911
1912
1913
1914
1915
1916
1917
 
# File 'lib/docusign_rest/client.rb', line 1897

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

  uri = build_uri("/accounts/#{@acct_id}/signing_groups/#{options[:signing_group_id]}/users")

  users = options[:users]
  users.each do |user|
   user[:userName] = user.delete(:user_name) if user.key?(:user_name)
  end
  post_body = {
    users: users
  }.to_json

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

#void_envelope(options = {}) ⇒ Object

Public voids an in-process envelope

envelope_id - ID of the envelope to be voided voided_reason - Optional reason for the envelope being voided

Returns the response (success or failure).



1621
1622
1623
1624
1625
1626
1627
1628
1629
1630
1631
1632
1633
1634
1635
1636
1637
1638
 
# File 'lib/docusign_rest/client.rb', line 1621

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

  post_body = {
      "status" =>"voided",
      "voidedReason" => options[:voided_reason] || "No reason provided."
  }.to_json

  uri = build_uri("/accounts/#{acct_id}/envelopes/#{options[:envelope_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)
  generate_log(request, response, uri)
  response
end