Module: Echochamber::Request

Defined in:
lib/echochamber/request.rb,
lib/echochamber/widget/request.rb,
lib/echochamber/agreement/request.rb,
lib/echochamber/library_documents/request.rb

Defined Under Namespace

Classes: Failure

Constant Summary collapse

BASE_URL = 
'https://secure.echosign.com/api/rest/v2'
ENDPOINT = 
{ 
  token: BASE_URL + '/auth/tokens',
  user: BASE_URL + '/users',
  agreement: BASE_URL + '/agreements',
  reminder: BASE_URL + '/reminders',
  transientDocument: BASE_URL + '/transientDocuments',
  libraryDocument: BASE_URL + '/libraryDocuments',
  widget: BASE_URL + '/widgets'
}

Class Method Summary collapse

Class Method Details

.agreement_combined_pdf(token, agreement_id, versionId, participantEmail, attachSupportingDocuments, auditReport) ⇒ String

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

Parameters:

  • token (String) —

    Auth Token

  • agreement_id (String) —

    ID of agreement to retrieve info on.

Returns:

  • (String) —

    Raw bytes from document file



57
58
59
60
61
62
63
64
65
 
# File 'lib/echochamber/agreement/request.rb', line 57

def self.agreement_combined_pdf(token, agreement_id, versionId, participantEmail, attachSupportingDocuments, auditReport)
  headers = { 'Access-Token' => token }
  endpoint = "#{ENDPOINT.fetch(:agreement)}/#{agreement_id}/combinedDocument"
  endpoint << add_query(endpoint, "versionId=#{versionId}") unless versionId.nil?
  endpoint << add_query(endpoint, "participantEmail=#{participantEmail}") unless participantEmail.nil?
  endpoint << add_query(endpoint, "attachSupportingDocuments=#{attachSupportingDocuments}")
  endpoint << add_query(endpoint, "auditReport=#{auditReport}")
  response = get(endpoint, headers)
end

.agreement_document_file(token, agreement_id, document_id) ⇒ String

Retrieve agreement document PDF

Parameters:

  • token (String) —

    Auth Token

  • agreement_id (String) —

    ID of agreement to retrieve info on.

Returns:

  • (String) —

    Raw bytes from document file



83
84
85
86
87
 
# File 'lib/echochamber/agreement/request.rb', line 83

def self.agreement_document_file(token, agreement_id, document_id)
  headers = { 'Access-Token' => token }
  endpoint = "#{ENDPOINT.fetch(:agreement)}/#{agreement_id}/documents/#{document_id}"
  response = get(endpoint, headers)
end

.agreement_documents(token, agreement_id, recipient_email = nil, format = nil, version_id = nil) ⇒ Hash

Performs REST GET /agreement/:id/documents

Parameters:

  • agreement_id (String) —

    (REQUIRED)

  • recipient_email (String) (defaults to: nil) —

    The email address of the participant to be used to retrieve documents. (REQUIRED)

  • format (String) (defaults to: nil) —

    Content format of the supported documents. It can have two possible values ORIGINAL or CONVERTED_PDF. (REQUIRED)

  • version_id (String) (defaults to: nil) —

    Version of the agreement as provided by agreement_info. If not provided, the latest version of the agreement is used.

Returns:

  • (Hash) —

    Agreement documents response body



107
108
109
110
111
112
113
114
115
 
# File 'lib/echochamber/agreement/request.rb', line 107

def self.agreement_documents(token, agreement_id, recipient_email=nil, format=nil, version_id=nil)
  headers = { :accept => :json, 'Access-Token' => token }
  endpoint = "#{ENDPOINT.fetch(:agreement)}/#{agreement_id}/documents"
  endpoint << add_query(endpoint, "versionId=#{version_id}") unless version_id.nil?
  endpoint << add_query(endpoint, "participantEmail=#{recipient_email}") unless version_id.nil?
  endpoint << add_query(endpoint, "supportingDocumentContentFormat=#{format}") unless format.nil?
  response = get(endpoint, headers)
  JSON.parse(response.body)
end

.agreement_form_data(token, agreement_id) ⇒ String

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

Parameters:

  • token (String) —

    Auth Token

  • agreement_id (String) —

    (REQUIRED)

Returns:

  • (String) —

    Raw bytes representing CSV file



72
73
74
75
76
 
# File 'lib/echochamber/agreement/request.rb', line 72

def self.agreement_form_data(token, agreement_id)
  headers = { 'Access-Token' => token }
  endpoint = "#{ENDPOINT.fetch(:agreement)}/#{agreement_id}/formData"
  response = get(endpoint, headers)
end

.agreement_info(token, agreement_id) ⇒ Hash

Performs REST GET /agreement/:id operation

Parameters:

  • token (String) —

    Auth Token

  • agreement_id (String) —

    ID of agreement to retrieve info on.

Returns:

  • (Hash) —

    Agreement info response body



33
34
35
36
37
38
 
# File 'lib/echochamber/agreement/request.rb', line 33

def self.agreement_info(token, agreement_id)
  headers = { :accept => :json, 'Access-Token' => token }
  endpoint = "#{ENDPOINT.fetch(:agreement)}/#{agreement_id}"
  response = get(endpoint, headers)
  JSON.parse(response.body)
end

.agreement_signing_urls(token, agreement_id) ⇒ Hash

Performs REST GET /agreement/:id/signingUrls operation

Parameters:

  • token (String) —

    Auth Token

  • agreement_id (String) —

    ID of agreement to retrieve info on.

Returns:

  • (Hash) —

    URL information for the eSign page of the agreement



45
46
47
48
49
50
 
# File 'lib/echochamber/agreement/request.rb', line 45

def self.agreement_signing_urls(token, agreement_id)
  headers = { 'Access-Token' => token }
  endpoint = "#{ENDPOINT.fetch(:agreement)}/#{agreement_id}/signingUrls"
  response = get(endpoint, headers)
  JSON.parse(response.body)
end

.audit_trail_pdf(token, agreement_id) ⇒ String

Performs REST GET /agreement/:id/auditTrail operation

Parameters:

  • token (String) —

    Auth Token

  • agreement_id (String) —

    ID of agreement to retrieve info on.

Returns:

  • (String) —

    Raw bytes from audit pdf file



94
95
96
97
98
 
# File 'lib/echochamber/agreement/request.rb', line 94

def self.audit_trail_pdf(token, agreement_id)
  headers = { 'Access-Token' => token }
  endpoint = "#{ENDPOINT.fetch(:agreement)}/#{agreement_id}/auditTrail"
  response = get(endpoint, headers)
end

.create_agreement(body, token, user_id = nil, user_email = nil) ⇒ Hash

Performs REST create_agreement operation

Parameters:

  • body (Hash) —

    Request body (REQUIRED)

  • token (String) —

    Auth token (REQUIRED)

  • user_id (String) (defaults to: nil) —

    Echosign user ID (REQUIRED)

  • user_email (String) (defaults to: nil) —

    Echosign user email

Returns:

  • (Hash) —

    Agreement response body



10
11
12
13
14
15
16
 
# File 'lib/echochamber/agreement/request.rb', line 10

def self.create_agreement(body, token, user_id=nil, user_email=nil)
  headers = { :content_type => :json, :accept => :json, 'Access-Token' => token }
  headers.merge!('X-User-Id' => user_id) unless user_id.nil?
  headers.merge!('X-User-Email' => user_email) unless user_email.nil?
  response = post(ENDPOINT.fetch(:agreement), body, headers)
  JSON.parse(response.body)
end

.create_reminder(token, body) ⇒ Hash

Sends a reminder for an agreement.

Parameters:

  • body (Hash) —

    Valid request body

  • token (String) —

    Auth Token

Returns:

  • (Hash) —

    Response body



56
57
58
59
60
61
 
# File 'lib/echochamber/request.rb', line 56

def self.create_reminder(token, body)
endpoint = ENDPOINT.fetch(:reminder)
headers = { :content_type => :json, :accept => :json, 'Access-Token' => token}
response = post(endpoint, body, headers)
JSON.parse(response.body)
end

.create_transient_document(token, file_name, file_handle, mime_type = nil) ⇒ Hash

Performs REST create_transient_document operation

Parameters:

  • token (String) —

    Auth token (REQUIRED)

  • file_name (String) —

    File name (REQUIRED)

  • file_handle (File) —

    File handle (REQUIRED)

  • mime_type (String) (defaults to: nil) —

    Mime type

Returns:

  • (Hash) —

    Transient Document Response Body



70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
 
# File 'lib/echochamber/request.rb', line 70

def self.create_transient_document(token, file_name, file_handle, mime_type=nil)
  headers = { :content_type => :json, :accept => :json, 'Access-Token' => token }

  begin
    response = RestClient.post( 
                               ENDPOINT.fetch(:transientDocument), 
                               { 'File-Name' => file_name, 
                                 'Mime-Type' => mime_type, 
                                 'File' => file_handle,  
                                 :multipart => true}, 
                                 headers
                              )
  rescue Exception => error
    raise_error(error)
  end

  JSON.parse(response.body)
end

.create_user(body, token) ⇒ Hash

Performs REST create_user operation

Parameters:

  • body (Hash) —

    Valid request body

  • token (String) —

    Auth Token

Returns:

  • (Hash) —

    New user response body



44
45
46
47
48
49
 
# File 'lib/echochamber/request.rb', line 44

def self.create_user(body, token)
  endpoint = ENDPOINT.fetch(:user) 
  headers = { :content_type => :json, :accept => :json, 'Access-Token' => token}
  response = post(endpoint, body, headers)
  JSON.parse(response.body)
end

.create_widget(token, widget) ⇒ Hash

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

Parameters:

Returns:

  • (Hash) 


8
9
10
11
12
13
14
15
 
# File 'lib/echochamber/widget/request.rb', line 8

def self.create_widget(token, widget)
  endpoint = ENDPOINT.fetch(:widget) 
  headers = { :content_type => :json, :accept => :json, 'Access-Token' => token}
  headers.merge!('X-User-Id' => widget.user_id) unless widget.user_id.nil?
  headers.merge!('X-User-Email' => widget.user_email) unless widget.user_email.nil?
  response = post(endpoint, widget, headers)
  JSON.parse(response.body)
end

.get_agreements(token) ⇒ Hash

Performs REST GET /agreements operation

Parameters:

  • token (String) —

    Auth Token

Returns:

  • (Hash) —

    Agreements response body



22
23
24
25
26
 
# File 'lib/echochamber/agreement/request.rb', line 22

def self.get_agreements(token)
  headers = { :accept => :json, 'Access-Token' => token }
  response = get(ENDPOINT.fetch(:agreement), headers)
  JSON.parse(response.body)
end

.get_library_document(token, library_document_id) ⇒ Hash

Retrieves library document metadata for a user.

Parameters:

  • token (String) —

    Auth Token

  • library_document_id (String)

Returns:

  • (Hash) —

    Library document metadata



23
24
25
26
27
28
 
# File 'lib/echochamber/library_documents/request.rb', line 23

def self.get_library_document(token, library_document_id)
  headers = { 'Access-Token' => token }
  endpoint = "#{ENDPOINT.fetch(:libraryDocument)}/#{library_document_id}"
  response = get(endpoint, headers)
  JSON.parse(response)
end

.get_library_document_file(token, library_document_id, file_id) ⇒ String

Retrieves library document file data

Parameters:

  • token (String) —

    Auth Token

  • library_document_id (String) —

    (REQUIRED)

  • file_id (String) —

    (REQUIRED)

Returns:

  • (String) —

    Library document file data



48
49
50
51
52
 
# File 'lib/echochamber/library_documents/request.rb', line 48

def self.get_library_document_file(token, library_document_id, file_id)
  headers = { 'Access-Token' => token }
  endpoint = "#{ENDPOINT.fetch(:libraryDocument)}/#{library_document_id}/documents/#{file_id}"
  response = get(endpoint, headers)
end

.get_library_document_files(token, library_document_id) ⇒ Hash

Retrieves library document file

Parameters:

  • token (String) —

    Auth Token

  • library_document_id (String) —

    (REQUIRED)

Returns:

  • (Hash) —

    Library document files metadata



35
36
37
38
39
40
 
# File 'lib/echochamber/library_documents/request.rb', line 35

def self.get_library_document_files(token, library_document_id)
  headers = { 'Access-Token' => token }
  endpoint = "#{ENDPOINT.fetch(:libraryDocument)}/#{library_document_id}/documents"
  response = get(endpoint, headers)
  JSON.parse(response)
end

.get_library_documents(token, user_id = nil, user_email = nil) ⇒ Hash

Retrieves library documents for a user.

Parameters:

  • token (String) —

    Auth Token

  • user_id (String) (defaults to: nil) —

    The ID of the user whose library documents are being requested.

  • user_email (String) (defaults to: nil) —

    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.

Returns:

  • (Hash) —

    Library documents metadata



9
10
11
12
13
14
15
16
 
# File 'lib/echochamber/library_documents/request.rb', line 9

def self.get_library_documents(token, user_id=nil, user_email=nil)
  headers = { 'Access-Token' => token }
  headers.merge!('X-User-Id' => user_id) unless user_id.nil?
  headers.merge!('X-User-Email' => user_email) unless user_email.nil?
  endpoint = ENDPOINT.fetch(:libraryDocument)
  response = get(endpoint, headers)
  JSON.parse(response)
end

.get_token(credentials) ⇒ String

Retrieves the authentication token

Parameters:

Returns:

  • (String) —

    Valid authentication token



32
33
34
35
36
37
 
# File 'lib/echochamber/request.rb', line 32

def self.get_token(credentials)
  headers = { :content_type => :json, :accept => :json  }
  response = post(ENDPOINT.fetch(:token), credentials, headers)
  response_body = JSON.parse(response.body)
  response_body.fetch("accessToken")
end

.get_user(token, user_id) ⇒ Hash

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

Parameters:

  • token (String) —

    Auth Token

  • user_id (String)

Returns:

  • (Hash) —

    User info hash



106
107
108
109
110
111
 
# File 'lib/echochamber/request.rb', line 106

def self.get_user(token, user_id)
  headers = { 'Access-Token' => token }
  endpoint = "#{ENDPOINT.fetch(:user)}/#{user_id}"
  response = get(endpoint, headers)
  JSON.parse(response)
end

.get_users(token, user_email) ⇒ Hash

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

Parameters:

  • token (String) —

    Auth Token

  • user_email (String) —

    The email address of the user whose details are being requested.

Returns:

  • (Hash) —

    User info hash



94
95
96
97
98
99
 
# File 'lib/echochamber/request.rb', line 94

def self.get_users(token, user_email)
  headers = { 'Access-Token' => token }
  endpoint = "#{ENDPOINT.fetch(:user)}?x-user-email=#{user_email}"
  response = get(endpoint, headers)
  JSON.parse(response)
end

.get_widget(token, widget_id) ⇒ Hash

Performs GET /widget operation

Parameters:

  • widget_id (String)

Returns:

  • (Hash) —

    Response body



82
83
84
85
86
87
 
# File 'lib/echochamber/widget/request.rb', line 82

def self.get_widget(token, widget_id)
  headers = { :content_type => :json, :accept => :json, 'Access-Token' => token }
  endpoint = "#{ENDPOINT.fetch(:widget)}/#{widget_id}"
  response = get(endpoint, headers)
  JSON.parse(response.body)
end

.get_widget_audit_trail(token, widget_id) ⇒ Hash

Performs GET /widget/:id/auditTrail

Parameters:

  • widget_id (String)

Returns:

  • (Hash) —

    Response body



116
117
118
119
120
 
# File 'lib/echochamber/widget/request.rb', line 116

def self.get_widget_audit_trail(token, widget_id)
  headers = { :content_type => :json, :accept => :json, 'Access-Token' => token }
  endpoint = "#{ENDPOINT.fetch(:widget)}/#{widget_id}/auditTrail"
  response = get(endpoint, headers)
end

.get_widget_document_file(token, widget_id, document_id) ⇒ Hash

Performs GET /widget/:id/documents/:id operation

Parameters:

  • widget_id (String)

Returns:

  • (Hash) —

    Response body



106
107
108
109
110
 
# File 'lib/echochamber/widget/request.rb', line 106

def self.get_widget_document_file(token, widget_id, document_id)
  headers = { :content_type => :json, :accept => :json, 'Access-Token' => token }
  endpoint = "#{ENDPOINT.fetch(:widget)}/#{widget_id}/documents/#{document_id}"
  response = get(endpoint, headers)
end

.get_widget_documents(token, widget_id, version_id = nil, participant_email = nil) ⇒ Hash

Performs GET /widget/:id/documents operation

Parameters:

  • widget_id (String)

Returns:

  • (Hash) —

    Response body



93
94
95
96
97
98
99
100
 
# File 'lib/echochamber/widget/request.rb', line 93

def self.get_widget_documents(token, widget_id, version_id=nil, participant_email=nil)
  headers = { :content_type => :json, :accept => :json, 'Access-Token' => token }
  endpoint = "#{ENDPOINT.fetch(:widget)}/#{widget_id}/documents"
  endpoint << add_query(endpoint, "versionId=#{version_id}") unless version_id.nil?
  endpoint << add_query(endpoint, "participantEmail=#{participant_email}") unless participant_email.nil?
  response = get(endpoint, headers)
  JSON.parse(response.body)
end

.get_widget_form_data(token, widget_id) ⇒ Hash

Performs GET /widget/:id/formData

Parameters:

  • widget_id (String)

Returns:

  • (Hash) —

    Response body



126
127
128
129
130
 
# File 'lib/echochamber/widget/request.rb', line 126

def self.get_widget_form_data(token, widget_id)
  headers = { :content_type => :json, :accept => :json, 'Access-Token' => token }
  endpoint = "#{ENDPOINT.fetch(:widget)}/#{widget_id}/formData"
  response = get(endpoint, headers)
end

.get_widgets(token, user_id = nil, user_email = nil) ⇒ Hash

Performs GET /widgets operation

Parameters:

  • token (String) —

    Auth Token

  • user_id (String) (defaults to: nil)
  • user_email (String) (defaults to: nil)

Returns:

  • (Hash) —

    Response body



69
70
71
72
73
74
75
76
 
# File 'lib/echochamber/widget/request.rb', line 69

def self.get_widgets(token, user_id=nil, user_email=nil)
  headers = { :content_type => :json, :accept => :json, 'Access-Token' => token }
  headers.merge!('X-User-Id' => user_id) unless user_id.nil?
  headers.merge!('X-User-Email' => user_email) unless user_email.nil?
  endpoint = "#{ENDPOINT.fetch(:widget)}"
  response = get(endpoint, headers)
  JSON.parse(response.body)
end

.library_combined_document(token, library_document_id, auditReport) ⇒ String

Retrieves library combined document file

Parameters:

  • token (String) —

    Auth Token

  • library_document_id (String) —

    (REQUIRED)

Returns:

  • (String) —

    Raw library combined document file data



70
71
72
73
74
75
 
# File 'lib/echochamber/library_documents/request.rb', line 70

def self.library_combined_document(token, library_document_id, auditReport)
  headers = { 'Access-Token' => token }
  endpoint = "#{ENDPOINT.fetch(:libraryDocument)}/#{library_document_id}/combinedDocument"
  endpoint << add_query(endpoint, "auditReport=#{auditReport}") 
  response = get(endpoint, headers)
end

.library_document_audit_trail(token, library_document_id) ⇒ String

Retrieves library document file data

Parameters:

  • token (String) —

    Auth Token

  • library_document_id (String) —

    (REQUIRED)

Returns:

  • (String) —

    Library document file data



59
60
61
62
63
 
# File 'lib/echochamber/library_documents/request.rb', line 59

def self.library_document_audit_trail(token, library_document_id)
  headers = { 'Access-Token' => token }
  endpoint = "#{ENDPOINT.fetch(:libraryDocument)}/#{library_document_id}/auditTrail"
  response = get(endpoint, headers)
end

.personalize_widget(token, widget_id, personalization) ⇒ Hash

Performs REST PUT /agreement/:id operation

Parameters:

Returns:

  • (Hash) —

    Response body



23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
 
# File 'lib/echochamber/widget/request.rb', line 23

def self.personalize_widget(token, widget_id, personalization)
  headers = { :content_type => :json, :accept => :json, 'Access-Token' => token }
  endpoint = "#{ENDPOINT.fetch(:widget)}/#{widget_id}/personalize"

  begin
    response = RestClient.put(
      endpoint, 
      personalization.to_json,
      headers
    )
  rescue Exception => error
    raise_error(error)
  end

  JSON.parse(response.body)
end

.update_agreement_status(token, agreement_id, request_body) ⇒ Hash

Performs REST PUT /agreement/:id operation

Parameters:

  • token (String) —

    Auth Token

  • agreement_id (String) —

    ID of agreement to retrieve info on.

  • request_body (Hash) —

    Hash for Agreement status update

Returns:

  • (Hash) —

    Agreements response body



124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
 
# File 'lib/echochamber/agreement/request.rb', line 124

def self.update_agreement_status(token, agreement_id, request_body)
  headers = { :content_type => :json, :accept => :json, 'Access-Token' => token }
  endpoint = "#{ENDPOINT.fetch(:agreement)}/#{agreement_id}/status"

  begin
    response = RestClient.put(
      endpoint, 
      request_body.to_json,
      headers
    )
  rescue Exception => error
    raise_error(error)
  end

  JSON.parse(response.body)
end

.update_widget_status(token, widget_id, status) ⇒ Hash

Performs REST PUT /agreement/:id operation

Parameters:

Returns:

  • (Hash) —

    Response body



46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
 
# File 'lib/echochamber/widget/request.rb', line 46

def self.update_widget_status(token, widget_id, status)
  headers = { :content_type => :json, :accept => :json, 'Access-Token' => token }
  endpoint = "#{ENDPOINT.fetch(:widget)}/#{widget_id}/status"

  begin
    response = RestClient.put(
      endpoint, 
      status.to_json,
      headers 
    )
  rescue Exception => error
    raise_error(error)
  end

  JSON.parse(response.body)
end