Module: RightSignature::Document

Includes:
Helpers
Included in:
Connection
Defined in:
lib/rightsignature/document.rb

Instance Method Summary collapse

Methods included from Helpers

#array_to_acceptable_names_hash

Instance Method Details

#document_details(guid) ⇒ Object

Gets details for a document

  • guids: Array of document GUIDs

Ex. Get details for document GUID123

@rs_connection.document_details("GUID123")



47
48
49
 
# File 'lib/rightsignature/document.rb', line 47

def document_details(guid)
  get "/api/documents/#{guid}.xml"
end

#documents_batch_details(guids) ⇒ Object

Gets details for multiple documents.

  • guids: Array of document GUIDs

Ex. Get details for documents GUID123 and GUID345

@rs_connection.documents_batch_details(["GUID123","GUID345"])



57
58
59
 
# File 'lib/rightsignature/document.rb', line 57

def documents_batch_details(guids)
  get "/api/documents/#{guids.join(',')}/batch_details.xml"
end

#documents_list(options = {}) ⇒ Object

Lists documents

* <b>options</b>: (optional) search filters
  * <b>:state</b> - (completed/trashed/pending) filter by state
  * <b>:page</b> - page offset
  * <b>:per_page</b> - # of entries per page to return
  * <b>:search</b> - search term filter
  * <b>:tags</b> - tags filter. Array of ["single_tag", {"tag_key" => "tag_value"}]
  * <b>:sort</> - sort documents by given attribute.
  API supports 'created', 'completed', and 'activity'
  * <b>:range</b> - ('today'/'thisweek'/'thismonth'/'alltime'/Date) return documents with a certain date range.
  * <b> :recipient_email</b> - filter document where it has a recipient with given email and involves the current OAuth user.
  * <b> :account</b> - (true/false) include all documents in current account if true.

Ex.

options = {
  :state => ['completed', 'trashed'],
  :page => 1,
  :per_page => 20,
  :search => "me",
  :tags => ["single_tag", "key" => "with_value"]
}

@rs_connection.documents_list(options)



31
32
33
34
35
36
37
38
39
 
# File 'lib/rightsignature/document.rb', line 31

def documents_list(options={})
  if options[:metadata]
    options[:tags] = TagsHelper.array_and_metadata_to_string_array(options[:tags], options.delete(:metadata))
  elsif options[:tags]
    options[:tags] = TagsHelper.mixed_array_to_string_array(options[:tags])
  end
  options[:state] = options[:state].join(',') if options[:state] && options[:state].is_a?(Array)
  get "/api/documents.xml", options
end

#extend_document_expiration(guid) ⇒ Object

Extends a document’s expiration date by 7 days

  • guid: Document GUID

Ex. Extend expiration for document GUID123 by 7 days

@rs_connection.extend_document_expiration("GUID123")



88
89
90
 
# File 'lib/rightsignature/document.rb', line 88

def extend_document_expiration(guid)
  post "/api/documents/#{guid}/extend_expiration.xml", {}
end

#generate_document_redirect_url(subject, recipients, document_data, options = {}) ⇒ Object

Prefills a document from a base64 encoded file or publicly available URL and returns a url that allows someone to send as the API User

  • document_data: hash of document source :type (‘base64’ or ‘url’), :filename to be used, :value of source (url or base64 encoded binary)

  • subject: subject of the document that’ll appear in email

  • recipients: Recipients of the document, should be an array of hashes with :name, :email, and :role (‘cc’ or ‘signer’). One of the recipients requires :is_sender (true/false) to reference the API User and won’t need to supply :name and :email Ex. CC to [email protected], with sender and [email protected] as a signer

    [
  {:name => "RightSignature", :email => "[email protected]", :role => 'cc'},
  {:name => "John Bellingham", :email => "[email protected]", :role => 'signer'},
  {'is_sender' => true, :role => 'signer'},
]

  • options: other optional values

    • description: document description that’ll appear in the email

    • action: ‘send’ or ‘redirect’. Redirect will return a token that will allow another person to send the document under API user’s account

    • expires_in: number of days before expiring the document. API only allows 2,5,15, or 30.

    • tags: document tags, an array of string or hashes ‘single_tag’ (for simple tag) or => ‘tag_value’ (for tuples pairs) Ex. [‘sent_from_api’, => “32”]

    • callback_location: A URI encoded URL that specifies the location for API to POST a callback notification to when the document has been created and signed. Ex. “yoursite/callback”

    • use_text_tags: Document has special Text Tags that RightSignature parse. true or false. More info: rightsignature.com/apidocs/text_tags

Ex.

recipients = [
  {:name => "RightSignature", :email => "[email protected]", :role => 'cc'},
  {:name => "John Bellingham", :email => "[email protected]", :role => 'signer'},
  {'is_sender' => true, :role => 'signer'},
]
document_data = {:type => 'base64', :filename => "originalfile.pdf", :value => Base64.encode64(File.read('myfile.pdf','r'))}
options = {
  :tags => ['sent_from_api', 'user_id' => '12345'],
  :expires_in => '5 days',
  :action => "redirect",
  'callback_location' => "http://example.com/doc_callback",
  'use_text_tags' => false
}
@rs_connection.generate_document_redirect_url( "My Subject", recipients, document_data, options)



299
300
301
302
303
304
 
# File 'lib/rightsignature/document.rb', line 299

def generate_document_redirect_url(subject, recipients, document_data, options={})
  options[:action] = "redirect"
  response = send_document(subject, recipients, document_data, options)

  "#{site}/builder/new?rt=#{response['document']['redirect_token']}"
end

#get_document_signer_links_for(guid, redirect_location = nil) ⇒ Object

Generates signer links for a Document with signers with email of “[email protected]”

  • guid: Document GUID

  • redirect_location: (Optional) URL to redirect each signer after it is completed

Ex. Generate signer links for document GUID123 that redirects users to mysite/done_signing after signing

@rs_connection.get_document_signer_links_for("GUID123", "http://mysite/done_signing")

Note that ONLY recipients with an email of “[email protected]” will have a signer link



314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
 
# File 'lib/rightsignature/document.rb', line 314

def get_document_signer_links_for(guid, redirect_location = nil)
  params = {}
  params[:redirect_location] = URI.encode(redirect_location) if redirect_location
  response = get "/api/documents/#{guid}/signer_links.xml", params

  signer_links = []

  if response["document"]["signer_links"] && response["document"]["signer_links"]["signer_link"].is_a?(Array)
    response["document"]["signer_links"]["signer_link"].each do |signer_link|
      signer_links << {"name" => signer_link["name"], "url" => "#{site}/signatures/embedded?rt=#{signer_link["signer_token"]}"}
    end
  elsif response["document"]["signer_links"]
    signer_link = response["document"]["signer_links"]["signer_link"]
    signer_links << {"name" => signer_link["name"], "url" => "#{site}/signatures/embedded?rt=#{signer_link["signer_token"]}"}
  end
  signer_links
end

#send_document(subject, recipients, document_data, options = {}) ⇒ Object

Creates a document from a base64 encoded file or publicly available URL

  • document_data: hash of document source :type (‘base64’ or ‘url’), :filename to be used, :value of source (url or base64 encoded binary)

  • subject: subject of the document that’ll appear in email

  • recipients: Recipients of the document, should be an array of hashes with :name, :email, and :role (‘cc’ or ‘signer’). One of the recipients requires :is_sender (true/false) to reference the API User and won’t need to supply :name and :email Ex. CC to [email protected], with sender and [email protected] as a signer

    [
  {:name => "RightSignature", :email => "[email protected]", :role => 'cc'},
  {:name => "John Bellingham", :email => "[email protected]", :role => 'signer'},
  {'is_sender' => true, :role => 'signer'},
]

  • options: other optional values

    • description: document description that’ll appear in the email

    • action: ‘send’ or ‘redirect’. Redirect will return a token that will allow another person to send the document under API user’s account

    • expires_in: number of days before expiring the document. API only allows 2,5,15, or 30.

    • tags: document tags, an array of string or hashes ‘single_tag’ (for simple tag) or => ‘tag_value’ (for tuples pairs)

      Ex. ['sent_from_api', {"user_id" => "32"}]

    • callback_location: A URI encoded URL that specifies the location for API to POST a callback notification to when the document has been created and signed.

      Ex. "http://yoursite/callback"

    • use_text_tags: Document has special Text Tags that RightSignature parse. true or false.

      More info: https://rightsignature.com/apidocs/text_tags

Ex.

recipients = [
  {:name => "RightSignature", :email => "[email protected]", :role => 'cc'},
  {:name => "John Bellingham", :email => "[email protected]", :role => 'signer'},
  {'is_sender' => true, :role => 'signer'},
]
document_data = {:type => 'base64', :filename => "originalfile.pdf", :value => Base64.encode64(File.read('myfile.pdf','r'))}
options = {
  :tags => ['sent_from_api', 'user_id' => '12345'],
  :expires_in => '5 days',
  :action => "redirect",
  'callback_location' => "http://example.com/doc_callback",
  'use_text_tags' => false
}
@rs_connection.send_document( "My Subject", recipients, document_data, options)



246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
 
# File 'lib/rightsignature/document.rb', line 246

def send_document(subject, recipients, document_data, options={})
  document_hash = {:document => {
    :subject => subject,
    :action => "send",
    :document_data => document_data
  }}

  document_hash[:document][:recipients] = []
  recipients.each do |recipient_hash|
    document_hash[:document][:recipients] << { :recipient => recipient_hash}
  end

  document_hash[:document].merge!(options)
  post "/api/documents.xml", document_hash
end

#send_document_from_data(file_data, filename, subject, recipients, options = {}) ⇒ Object

Creates a document from a raw data

  • file: file binary. Ex. File.read(‘myfile.pdf’)

  • filename: original filename

  • subject: subject of the document that’ll appear in email

  • recipients: Recipients of the document, should be an array of hashes with :name, :email, and :role (‘cc’ or ‘signer’). One of the recipients requires :is_sender (true/false) to reference the API User and won’t need to supply :name and :email Ex. CC to [email protected], with sender and [email protected] as a signer

    [
  {:name => "RightSignature", :email => "[email protected]", :role => 'cc'},
  {:name => "John Bellingham", :email => "[email protected]", :role => 'signer'},
  {'is_sender' => true, :role => 'signer'},
]

  • options: other optional values

    • description: document description that’ll appear in the email

    • action: ‘send’ or ‘redirect’. Redirect will return a token that will allow another person to send the document under API user’s account

    • expires_in: number of days before expiring the document. API only allows 2,5,15, or 30.

    • tags: document tags, an array of string or hashes ‘single_tag’ (for simple tag) or => ‘tag_value’ (for tuples pairs) Ex. [‘sent_from_api’, => “32”]

    • callback_location: A URI encoded URL that specifies the location for API to POST a callback notification to when the document has been created and signed. Ex. “yoursite/callback”

    • use_text_tags: Document has special Text Tags that RightSignature parse. true or false. More info: rightsignature.com/apidocs/text_tags



123
124
125
 
# File 'lib/rightsignature/document.rb', line 123

def send_document_from_data(file_data, filename, subject, recipients, options={})
  send_document(subject, recipients, {:type => "base64", :filename => filename, :value => Base64::encode64(file_data)}, options)
end

#send_document_from_file(file, subject, recipients, options = {}) ⇒ Object

Creates a document from a File or path to file

  • file: Path to file or File object

  • subject: subject of the document that’ll appear in email

  • recipients: Recipients of the document, should be an array of hashes with :name, :email, and :role (‘cc’ or ‘signer’). One of the recipients requires :is_sender (true/false) to reference the API User and won’t need to supply :name and :email Ex. CC to [email protected], with sender and [email protected] as a signer

    [
  {:name => "RightSignature", :email => "[email protected]", :role => 'cc'},
  {:name => "John Bellingham", :email => "[email protected]", :role => 'signer'},
  {'is_sender' => true, :role => 'signer'},
]

  • options: other optional values

    • description: document description that’ll appear in the email

    • action: ‘send’ or ‘redirect’. Redirect will return a token that will allow another person to send the document under API user’s account

    • expires_in: number of days before expiring the document. API only allows 2,5,15, or 30.

    • tags: document tags, an array of string or hashes ‘single_tag’ (for simple tag) or => ‘tag_value’ (for tuples pairs)

      Ex. ['sent_from_api', {"user_id" => "32"}]

    • callback_location: A URI encoded URL that specifies the location for API to POST a callback notification to when the document has been created and signed.

      Ex. "http://yoursite/callback"

    • use_text_tags: Document has special Text Tags that RightSignature parse. true or false.

      More info: https://rightsignature.com/apidocs/text_tags

Example:

recipients = [
  {:name => "RightSignature", :email => "[email protected]", :role => 'cc'},
  {:name => "John Bellingham", :email => "[email protected]", :role => 'signer'},
  {'is_sender' => true, :role => 'signer'}
]
options={
  :tags => [{:tag => {:name => 'sent_from_api'}}, {:tag => {:name => 'user_id', :value => '12345'}}],
  :expires_in => '5 days',
  :action => "redirect",
  'callback_location' => "http://example.com/doc_callback",
  'use_text_tags' => false
}
@rs_connection.send_document_from_file("here/is/myfile.pdf", 'My Subject', recipients, options)



164
165
166
 
# File 'lib/rightsignature/document.rb', line 164

def send_document_from_file(file, subject, recipients, options={})
  send_document(subject, recipients, {:type => "base64", :filename => File.basename(file), :value => Base64::encode64(File.read(file)) }, options)
end

#send_document_from_url(url, subject, recipients, options = {}) ⇒ Object

Creates a document from URL

  • url: URL to file

  • subject: subject of the document that’ll appear in email

  • recipients: Recipients of the document, should be an array of hashes with :name, :email, and :role (‘cc’ or ‘signer’). One of the recipients requires :is_sender (true/false) to reference the API User and won’t need to supply :name and :email Ex. CC to [email protected], with sender and [email protected] as a signer

    [
  {:name => "RightSignature", :email => "[email protected]", :role => 'cc'},
  {:name => "John Bellingham", :email => "[email protected]", :role => 'signer'},
  {'is_sender' => true, :role => 'signer'},
]

  • options: other optional values

    • description: document description that’ll appear in the email

    • action: ‘send’ or ‘redirect’. Redirect will return a token that will allow another person to send the document under API user’s account

    • expires_in: number of days before expiring the document. API only allows 2,5,15, or 30.

    • tags: document tags, an array of string or hashes ‘single_tag’ (for simple tag) or => ‘tag_value’ (for tuples pairs)

      Ex. ['sent_from_api', {"user_id" => "32"}]

    • callback_location: A URI encoded URL that specifies the location for API to POST a callback notification to when the document has been created and signed.

      Ex. "http://yoursite/callback"

    • use_text_tags: Document has special Text Tags that RightSignature parse. true or false.

      More info: https://rightsignature.com/apidocs/text_tags

Example:

recipients = [
  {:name => "RightSignature", :email => "[email protected]", :role => 'cc'},
  {:name => "John Bellingham", :email => "[email protected]", :role => 'signer'},
  {'is_sender' => true, :role => 'signer'}
]
options={
  :tags => [{:tag => {:name => 'sent_from_api'}}, {:tag => {:name => 'user_id', :value => '12345'}}],
  :expires_in => '5 days',
  :action => "redirect",
  'callback_location' => "http://example.com/doc_callback",
  'use_text_tags' => false
}
@rs_connection.send_document_from_url("http://myfile/here", 'My Subject', recipients, options)



205
206
207
 
# File 'lib/rightsignature/document.rb', line 205

def send_document_from_url(url, subject, recipients, options={})
  send_document(subject, recipients, {:type => "url", :filename => File.basename(url), :value => url }, options)
end

#send_reminder(guid) ⇒ Object

Sends a reminder for a document

  • guid: Document GUID

Ex. Sends reminder for document GUID123

@rs_connection.send_reminder("GUID123")



67
68
69
 
# File 'lib/rightsignature/document.rb', line 67

def send_reminder(guid)
  post "/api/documents/#{guid}/send_reminders.xml", {}
end

#trash_document(guid) ⇒ Object

Extends a document’s expiration date by 7 days

  • guid: Document GUID

Ex. Extend expiration for document GUID123 by 7 days

@rs_connection.trash_document("GUID123")



77
78
79
 
# File 'lib/rightsignature/document.rb', line 77

def trash_document(guid)
  post "/api/documents/#{guid}/trash.xml", {}
end

#update_document_tags(guid, tags) ⇒ Object

REPLACE the tags on a document tags are an array of ‘tag_name’ or => ‘value’

Ex. Replaces document GUID123 with tags “single_tag”, “hello:bye”

@rs_connection.update_document_tags("GUID123", ["single_tag", {"hello" => "bye"}])



97
98
99
 
# File 'lib/rightsignature/document.rb', line 97

def update_document_tags(guid, tags)
  post "/api/documents/#{guid}/update_tags.xml", { :tags => TagsHelper.array_to_xml_hash(tags) }
end