class Echosign::Client

Attributes

token[R]

Public Class Methods

new(token) click to toggle source

Initializes the Client object

@param token [String] Access token or integration key @return [Echochamber::Client] Initialized Echochamber::Client

# File lib/echosign/client.rb, line 13
def initialize(token)
  @token = token
  @base_uri = nil
end

Public Instance Methods

agreement_combined_pdf(agreement_id, file_path = nil, versionId = nil, participantEmail = nil, attachSupportingDocuments = true, auditReport = false) click to toggle source

Gets a single combined PDF document for the documents associated with an agreement.

@param agreement_id [String] (REQUIRED) @param file_path [String] File path to save the document. If no file path is given, nothing is saved to disk. @param versionId [String] The version identifier of agreement as provided by get_agreement. If not provided

then latest version will be used

@param participantEmail [String] The email address of the participant to be used to retrieve documents. If

none is given, the auth token will be used to determine the user

@param attachSupportingDocuments [Boolean] When set to YES, attach corresponding supporting documents to the

signed agreement PDF. Default value of this parameter is true.

@param auditReport [Boolean] When set to YES, attach an audit report to the signed agreement PDF. Default

value is false

@return [String] Raw bytes from document file

# File lib/echosign/agreement/client.rb, line 97
def agreement_combined_pdf(agreement_id, file_path = nil, versionId = nil, participantEmail = nil,
                           attachSupportingDocuments = true, auditReport = false)
  response = request(:agreement_combined_pdf, agreement_id, versionId, participantEmail, attachSupportingDocuments,
                     auditReport)
  unless file_path.nil?
    file = File.new(file_path, 'wb')
    file.write(response)
    file.close
  end
  response
end
agreement_document_file(agreement_id, document_id, file_path = nil) click to toggle source

Retrieve a document file from an agreement

@param agreement_id [String] (REQUIRED) @param document_id [String] (REQUIRED) @param file_path [String] File path to save the document. If no file path is given, nothing is saved to disk. @return [String] Raw bytes from document file

# File lib/echosign/agreement/client.rb, line 66
def agreement_document_file(agreement_id, document_id, file_path = nil)
  response = request(:agreement_document_file, agreement_id, document_id)
  unless file_path.nil?
    file = File.new(file_path, 'wb')
    file.write(response)
    file.close
  end
  response
end
agreement_documents(agreement_id, recipient_email, format, version_id = nil) click to toggle source

All documents relating to an agreement

@param agreement_id [String] (REQUIRED) @param recipient_email [String] The email address of the participant to be used to retrieve documents. (REQUIRED) @param format [String] Content format of the supported documents. It can have two possible values ORIGINAL or

CONVERTED_PDF. (REQUIRED)

@param version_id [String] Version of the agreement as provided by agreement_info(). If not provided, the

latest version of the agreement is used.

@return [Array] Documents relating to agreement.

# File lib/echosign/agreement/client.rb, line 56
def agreement_documents(agreement_id, recipient_email, format, version_id = nil)
  result = request(:agreement_documents, agreement_id, recipient_email, format, version_id)
end
agreement_form_data(agreement_id, file_path = nil) click to toggle source

Retrieves library document audit trail file

@param agreement_id [String] (REQUIRED) @param file_path [String] File path where to save the CSV file. If no file path is given, nothing is saved to

disk.

@return [String] Raw bytes representing CSV file

# File lib/echosign/agreement/client.rb, line 115
def agreement_form_data(agreement_id, file_path = nil)
  response = request(:agreement_form_data, agreement_id)
  unless file_path.nil?
    file = File.new(file_path, 'wb')
    file.write(response)
    file.close
  end
  response
end
agreement_info(agreement_id) click to toggle source

Gets detailed info on an agreement

@param agreement_id [String] ID of agreement to retrieve info on. @return [Hash] Detailed agreement info

# File lib/echosign/agreement/client.rb, line 26
def agreement_info(agreement_id)
  request(:agreement_info, agreement_id)
end
agreement_signing_urls(agreement_id) click to toggle source

Retrieves the URL for the eSign page for the current signer(s) of an agreement

@param agreement_id [String] (REQUIRED) @return [Hash] URL information for the eSign page of the agreement

# File lib/echosign/agreement/client.rb, line 80
def agreement_signing_urls(agreement_id)
  response = request(:agreement_signing_urls, agreement_id)
end
audit_trail_pdf(agreement_id, file_path = nil) click to toggle source

Retrieve a PDF audit file for an agreement

@param agreement_id [String] (REQUIRED) @param file_path [String] File path to save the document. If no file path is given, nothing is saved to disk. @return [String] Raw bytes from document file

# File lib/echosign/client.rb, line 51
def audit_trail_pdf(agreement_id, file_path = nil)
  response = request(:audit_trail_pdf, agreement_id)
  unless file_path.nil?
    file = File.new(file_path, 'wb')
    file.write(response)
    file.close
  end
  response
end
cancel_agreement(agreement_id, notify_signer = false, comment = nil) click to toggle source

Cancel agreement

@param agreement_id [String] (REQUIRED) @param notify_signer [Boolean] Whether to notify the signer by email of the cancellation. Default is false. @param comment [String] Comment regarding this cancellation. @return [String] Result of the operation

# File lib/echosign/agreement/client.rb, line 36
def cancel_agreement(agreement_id, notify_signer = false, comment = nil)
  request_body = {
    "value" => "CANCEL",
    "notifySigner" => notify_signer
  }
  request_body[:comment] = comment unless comment.nil?

  agreement_status_response = request(:update_agreement_status, agreement_id, request_body)
  agreement_status_response.fetch('result')
end
cancel_mega_sign(mega_sign_id, notify_signer = false, comment = nil) click to toggle source

Cancel mega_sign

@param mega_sign_id [String] (REQUIRED) @param notify_signer [Boolean] Whether to notify the signer by email of the cancellation. Default is false. @param comment [String] Comment regarding this cancellation. @return [String] Result of the operation

# File lib/echosign/mega_sign/client.rb, line 35
def cancel_mega_sign(mega_sign_id, notify_signer = false, comment = nil)
  request_body = {
    "value" => "CANCEL",
    "notifySigner" => notify_signer
  }
  request_body[:comment] = comment unless comment.nil?

  mega_sign_status_response = request(:update_mega_sign_status, mega_sign_id, request_body)
  mega_sign_status_response.fetch('result')
end
create_agreement(agreement) click to toggle source

Creates an agreement

@param agreement [Echosign::Agreement] @return [String] Agreement ID

# File lib/echosign/agreement/client.rb, line 7
def create_agreement(agreement)
  agreement_response = request(:create_agreement, agreement, agreement.user_id, agreement.user_email)
  return agreement_response['agreementId'] if agreement_response.has_key?('agreementId')

  raise "Error creating agreement - response was #{agreement_response}"
end
create_mega_sign(mega_sign) click to toggle source

Creates an mega_sign

@param mega_sign [Echosign::Agreement] @return [String] Agreement ID

# File lib/echosign/mega_sign/client.rb, line 7
def create_mega_sign(mega_sign)
  mega_sign_response = request(:create_mega_sign, mega_sign, mega_sign.user_id, mega_sign.user_email)
  puts mega_sign_response.inspect
  mega_sign_response.fetch("mega_signId")
end
create_reminder(reminder) click to toggle source

Creates a reminder

@param reminder [Echosign::Reminder] @return [String] Reminder ID

# File lib/echosign/client.rb, line 31
def create_reminder(reminder)
  reminder_response = request(:create_reminder, reminder)
end
create_transient_document(file_name, mime_type, file_handle) click to toggle source

Creates a transient document for later referral

@param file_name [String] @param mime_type [String] @param file_handle [File] @return [String] Transient document ID

# File lib/echosign/client.rb, line 41
def create_transient_document(file_name, mime_type, file_handle)
  transient_document_response = request(:create_transient_document, file_name, file_handle, mime_type)
  transient_document_response.fetch("transientDocumentId")
end
create_user(user) click to toggle source

Creates a user for the current application

@param user [Echosign::User] @return [String] User ID of new Echosign user

# File lib/echosign/client.rb, line 22
def create_user(user)
  user_response = request(:create_user, user)
  user_response.fetch("userId")
end
create_widget(widget) click to toggle source

Creates a widget and returns the Javascript snippet and URL to access the widget and widgetID in response to

the client

@param widget [Echosign::Widget] @return [Hash]

# File lib/echosign/widget/client.rb, line 8
def create_widget(widget)
  request(:create_widget, widget)
end
get_agreements() click to toggle source

Gets list of agreements

@return [Hash] An array of user agreement items

# File lib/echosign/agreement/client.rb, line 17
def get_agreements
  get_agreements_response = request(:get_agreements)
  get_agreements_response.fetch("userAgreementList")
end
get_library_document(library_document_id) click to toggle source

Retrieves library document metadata

@param library_document_id [String] (REQUIRED) @return [Hash] Library document metadata

# File lib/echosign/library_documents/client.rb, line 18
def get_library_document(library_document_id)
  request(:get_library_document, library_document_id)
end
get_library_document_file(library_document_id, file_id, file_path = nil) click to toggle source

Retrieves library document file data

@param library_document_id (REQUIRED) @param file_id [String] (REQUIRED) @param file_path [String] File path for saving the document. If none is given, nothing will be saved to disk. @return [String] Raw library document file data

# File lib/echosign/library_documents/client.rb, line 36
def get_library_document_file(library_document_id, file_id, file_path = nil)
  response = request(:get_library_document_file, library_document_id, file_id)
  unless file_path.nil?
    file = File.new(file_path, 'wb')
    file.write(response)
    file.close
  end
  response
end
get_library_document_files(library_document_id) click to toggle source

Retrieves library document files metadata

@param library_document_id [String] (REQUIRED) @return [Hash] Library document files metadata

# File lib/echosign/library_documents/client.rb, line 26
def get_library_document_files(library_document_id)
  request(:get_library_document_files, library_document_id)
end
get_library_documents(user_id = nil, user_email = nil) click to toggle source

Retrieves library documents metadata for a user.

@param user_id [String] The ID of the user whose library documents are being requested. @param user_email [String] The email address of the user whose library documents are being requested. If both

user_id and user_email are provided then user_id is given preference. If neither is specified then the user
is inferred from the access token.

@return [Hash] Library documents metadata

# File lib/echosign/library_documents/client.rb, line 10
def get_library_documents(user_id = nil, user_email = nil)
  request(:get_library_documents, user_id, user_email)
end
get_mega_signs() click to toggle source

Gets list of mega_signs

@return [Hash] An array of mega sign parent agreements

# File lib/echosign/mega_sign/client.rb, line 16
def get_mega_signs
  get_mega_signs_response = request(:get_mega_signs)
  get_mega_signs_response.fetch("megaSignList")
end
get_user(user_id) click to toggle source

Gets all the users in an account that the caller has permissions to access.

@param user_id [String] @return [Hash] User info hash

# File lib/echosign/client.rb, line 73
def get_user(user_id)
  request(:get_user, user_id)
end
get_users(user_email) click to toggle source

Gets all the users in an account that the caller has permissions to access.

@param user_email [String] The email address of the user whose details are being requested (REQUIRED) @return [Hash] User info hash

# File lib/echosign/client.rb, line 65
def get_users(user_email)
  request(:get_users, user_email)
end
get_widget(widget_id) click to toggle source

Retrieves the details of a widget

@param widget_id @return [Hash] Detailed widget info

# File lib/echosign/widget/client.rb, line 45
def get_widget(widget_id)
  request(:get_widget, widget_id)
end
get_widget_audit_trail(widget_id, file_path = nil) click to toggle source

Retrieves the audit trail of a widget identified by widgetId

@note SEEMINGLY NOT YET IMPLEMENTED SERVER-SIDE @param widget_id [String] @param file_path [String] File path where to save the document. If none is given, nothing will be saved to file. @return [String] Raw file stream

# File lib/echosign/widget/client.rb, line 82
def get_widget_audit_trail(widget_id, file_path = nil)
  response = request(:get_widget_audit_trail, widget_id)
  unless file_path.nil?
    file = File.new(file_path, 'wb')
    file.write(response)
    file.close
  end
  response
end
get_widget_combined_pdf(widget_id, file_path = nil) click to toggle source

Gets a single combined PDF document for the documents associated with a widget.

@note SEEMINGLY NOT YET IMPLEMENTED SERVER-SIDE @param widget_id [String] @param file_path [String] File path where to save the document. If none is given, nothing will be saved to file. @return [String] Raw file stream

# File lib/echosign/widget/client.rb, line 98
def get_widget_combined_pdf(widget_id, file_path = nil)
  response = request(:get_widget_combined_pdf, widget_id)
  unless file_path.nil?
    file = File.new(file_path, 'wb')
    file.write(response)
    file.close
  end
  response
end
get_widget_document_file(widget_id, document_id, file_path = nil) click to toggle source

Retrieves the file stream of a document of a widget

@param widget_id [String] @param document_id [String] @param file_path [String] File path where to save the document. If none is given, nothing will be saved to file. @return [String] Raw file stream

# File lib/echosign/widget/client.rb, line 66
def get_widget_document_file(widget_id, document_id, file_path = nil)
  response = request(:get_widget_document_file, widget_id, document_id)
  unless file_path.nil?
    file = File.new(file_path, 'wb')
    file.write(response)
    file.close
  end
  response
end
get_widget_documents(widget_id, version_id = nil, participant_email = nil) click to toggle source

Retrieves the IDs of the documents associated with widget.

@param widget_id [String] @param version_id [String] The version identifier of widget as provided by get_widget. If not provided then

latest version will be used.

@param participant_email [String] The email address of the participant to be used to retrieve documents @return [Hash] Info about widget documents

# File lib/echosign/widget/client.rb, line 56
def get_widget_documents(widget_id, version_id = nil, participant_email = nil)
  request(:get_widget_documents, widget_id, version_id, participant_email)
end
get_widget_form_data(widget_id, file_path = nil) click to toggle source

Retrieves data entered by the user into interactive form fields at the time they signed the widget

@note SEEMINGLY NOT YET IMPLEMENTED SERVER-SIDE @param widget_id [String] @param file_path [String] File path where to save the document. If none is given, nothing will be saved to file. @return [String] Raw file stream

# File lib/echosign/widget/client.rb, line 114
def get_widget_form_data(widget_id, file_path = nil)
  response = request(:get_widget_form_data, widget_id)
  unless file_path.nil?
    file = File.new(file_path, 'wb')
    file.write(response)
    file.close
  end
  response
end
get_widgets(user_id = nil, user_email = nil) click to toggle source

Retrieves widgets for a user

@param user_id [String] The ID of the user whose widgets are being requested @param user_email [String] The email address of the user whose widgets are being requested. If both user_id

and user_email are provided then user_id is given preference. If neither is specified then the user is
inferred from the access token

@return [Hash] Widgets info

# File lib/echosign/widget/client.rb, line 37
def get_widgets(user_id = nil, user_email = nil)
  request(:get_widgets, user_id, user_email)
end
library_combined_document(library_document_id, file_path = nil, auditReport = false) click to toggle source

Retrieves library combined document file

@param library_document_id (REQUIRED) @param file_path [String] File path for saving the document. If none is given, nothing will be saved to disk. @param auditReport [Boolean] When set to YES attach an audit report to the library document PDF. Default value

will be false.

@return [String] Raw library combined document file data

# File lib/echosign/library_documents/client.rb, line 68
def library_combined_document(library_document_id, file_path = nil, auditReport = false)
  response = request(:library_combined_document, library_document_id, auditReport)
  unless file_path.nil?
    file = File.new(file_path, 'wb')
    file.write(response)
    file.close
  end
  response
end
library_document_audit_trail(library_document_id, file_path = nil) click to toggle source

Retrieves library document audit trail file

@param library_document_id (REQUIRED) @param file_path [String] File path for saving the document. If none is given, nothing will be saved to disk. @return [String] Raw library document file data

# File lib/echosign/library_documents/client.rb, line 51
def library_document_audit_trail(library_document_id, file_path = nil)
  response = request(:library_document_audit_trail, library_document_id)
  unless file_path.nil?
    file = File.new(file_path, 'wb')
    file.write(response)
    file.close
  end
  response
end
mega_sign_combined_pdf(mega_sign_id, file_path = nil, versionId = nil, participantEmail = nil, attachSupportingDocuments = true, auditReport = false) click to toggle source

Gets a single combined PDF document for the documents associated with an mega_sign.

@param mega_sign_id [String] (REQUIRED) @param file_path [String] File path to save the document. If no file path is given, nothing is saved to disk. @param versionId [String] The version identifier of mega_sign as provided by get_mega_sign. If not provided

then latest version will be used

@param participantEmail [String] The email address of the participant to be used to retrieve documents. If

none is given, the auth token will be used to determine the user

@param attachSupportingDocuments [Boolean] When set to YES, attach corresponding supporting documents to the

signed mega_sign PDF. Default value of this parameter is true.

@param auditReport [Boolean] When set to YES, attach an audit report to the signed mega_sign PDF. Default

value is false

@return [String] Raw bytes from document file

# File lib/echosign/mega_sign/client.rb, line 96
def mega_sign_combined_pdf(mega_sign_id, file_path = nil, versionId = nil, participantEmail = nil,
                           attachSupportingDocuments = true, auditReport = false)
  response = request(:mega_sign_combined_pdf, mega_sign_id, versionId, participantEmail, attachSupportingDocuments,
                     auditReport)
  unless file_path.nil?
    file = File.new(file_path, 'wb')
    file.write(response)
    file.close
  end
  response
end
mega_sign_document_file(mega_sign_id, document_id, file_path = nil) click to toggle source

Retrieve a document file from an mega_sign

@param mega_sign_id [String] (REQUIRED) @param document_id [String] (REQUIRED) @param file_path [String] File path to save the document. If no file path is given, nothing is saved to disk. @return [String] Raw bytes from document file

# File lib/echosign/mega_sign/client.rb, line 65
def mega_sign_document_file(mega_sign_id, document_id, file_path = nil)
  response = request(:mega_sign_document_file, mega_sign_id, document_id)
  unless file_path.nil?
    file = File.new(file_path, 'wb')
    file.write(response)
    file.close
  end
  response
end
mega_sign_documents(mega_sign_id, recipient_email, format, version_id = nil) click to toggle source

All documents relating to an mega_sign

@param mega_sign_id [String] (REQUIRED) @param recipient_email [String] The email address of the participant to be used to retrieve documents. (REQUIRED) @param format [String] Content format of the supported documents. It can have two possible values ORIGINAL or

CONVERTED_PDF. (REQUIRED)

@param version_id [String] Version of the mega_sign as provided by mega_sign_info(). If not provided, the

latest version of the mega_sign is used.

@return [Array] Documents relating to mega_sign.

# File lib/echosign/mega_sign/client.rb, line 55
def mega_sign_documents(mega_sign_id, recipient_email, format, version_id = nil)
  result = request(:mega_sign_documents, mega_sign_id, recipient_email, format, version_id)
end
mega_sign_form_data(mega_sign_id, file_path = nil) click to toggle source

Retrieves library document audit trail file

@param mega_sign_id [String] (REQUIRED) @param file_path [String] File path where to save the CSV file. If no file path is given, nothing is saved to

disk.

@return [String] Raw bytes representing CSV file

# File lib/echosign/mega_sign/client.rb, line 114
def mega_sign_form_data(mega_sign_id, file_path = nil)
  response = request(:mega_sign_form_data, mega_sign_id)
  unless file_path.nil?
    file = File.new(file_path, 'wb')
    file.write(response)
    file.close
  end
  response
end
mega_sign_info(mega_sign_id) click to toggle source

Gets detailed info on an mega_sign

@param mega_sign_id [String] ID of mega_sign to retrieve info on. @return [Hash] Detailed mega_sign info

# File lib/echosign/mega_sign/client.rb, line 25
def mega_sign_info(mega_sign_id)
  request(:mega_sign_info, mega_sign_id)
end
mega_sign_signing_urls(mega_sign_id) click to toggle source

Retrieves the URL for the eSign page for the current signer(s) of an mega_sign

@param mega_sign_id [String] (REQUIRED) @return [Hash] URL information for the eSign page of the mega_sign

# File lib/echosign/mega_sign/client.rb, line 79
def mega_sign_signing_urls(mega_sign_id)
  response = request(:mega_sign_signing_urls, mega_sign_id)
end
personalize_widget(widget_id, personalization) click to toggle source

Personalize the widget to a signable document for a specific known user

@param widget_id @param personalization [Echosign::WidgetPersonalization] @return [Hash] Operation result

# File lib/echosign/widget/client.rb, line 17
def personalize_widget(widget_id, personalization)
  request(:personalize_widget, widget_id, personalization)
end
update_widget_status(widget_id, status) click to toggle source

Enables or Disables a widget

@param widget_id @param status [Echosign::WidgetStatus] @return [Hash] Widget status

# File lib/echosign/widget/client.rb, line 26
def update_widget_status(widget_id, status)
  request(:update_widget_status, widget_id, status)
end

Private Instance Methods

request(method, *params) click to toggle source

Call an Echosign::Request method with this client's token and base_uri

@param method [Symbol] The name of the ultimate method to call @param params Any number of parameters to be passed to the ultimate method @return Returns the result of the ultimate method

Note: params will be prepended with token and base_uri before calling the ultimate method

# File lib/echosign/client.rb, line 86
def request(method, *params)
  @base_uri ||= Echosign::Request.get_base_uris(@token).fetch('api_access_point')
  Echosign::Request.send(method, @token, @base_uri, *params)
end