Class: GroupDocs::Signature::Envelope

Inherits:
Api::Entity show all
Extended by:
ResourceMethods
Includes:
DocumentMethods, EntityFields, EntityMethods, FieldMethods, RecipientMethods
Defined in:
lib/groupdocs/signature/envelope.rb

Defined Under Namespace

Classes: Log

Constant Summary collapse

STATUSES = 
{
  draft:      -1,
  annotation:  0,
  in_progress: 1,
  expired:     2,
  canceled:    3,
  failed:      4,
  completed:   5,
  archived:    6,
}

Instance Attribute Summary collapse

Attributes included from EntityFields

#documentsCount, #documentsPages, #emailBody, #emailSubject, #id, #name, #orderedSignature, #ownerGuid, #ownerId, #ownerShouldSign, #recipients, #reminderTime, #stepExpireTime

Class Method Summary collapse

Instance Method Summary collapse

Methods included from ResourceMethods

resources!

Methods included from RecipientMethods

#recipients!, #remove_recipient!

Methods included from FieldMethods

#add_field!, #delete_field!, #delete_field_location!, #fields!, #modify_field!, #modify_field_location!

Methods included from EntityMethods

#create!, #delete!, included, #modify!, #rename!

Methods included from DocumentMethods

#add_document!, #documents!, #remove_document!

Methods inherited from Api::Entity

#initialize, #inspect, #to_hash

Constructor Details

This class inherits a constructor from GroupDocs::Api::Entity

Instance Attribute Details

#creationDateTime ⇒ Object Also known as: creation_date_time 



84
85
86
 
# File 'lib/groupdocs/signature/envelope.rb', line 84

def creationDateTime
  @creationDateTime
end

#envelopeExpireTime ⇒ Object Also known as: envelope_expire_time 



90
91
92
 
# File 'lib/groupdocs/signature/envelope.rb', line 90

def envelopeExpireTime
  @envelopeExpireTime
end

#status ⇒ Symbol

Converts status to human-readable format.

Returns:

  • (Symbol) 


86
87
88
 
# File 'lib/groupdocs/signature/envelope.rb', line 86

def status
  @status
end

#statusDateTime ⇒ Object Also known as: status_date_time 



88
89
90
 
# File 'lib/groupdocs/signature/envelope.rb', line 88

def statusDateTime
  @statusDateTime
end

Class Method Details

.all!(options = {}, access = {}) ⇒ Array<GroupDocs::Signature::Envelope>

Returns a list of all envelopes.

Parameters:

  • options (Hash) (defaults to: {}) —

    Hash of options

  • access (Hash) (defaults to: {}) —

    Access credentials

Options Hash (options):

  • :page (Integer) —

    Page to start with

  • :records (Integer) —

    How many items to list

  • :status_id (Integer) —

    Filter by status identifier

  • :document (String) —

    Filter by document GUID

  • :recipient (String) —

    Filter by recipient email

  • :date (String) —

    Filter by date

  • :name (String) —

    Filter by name

Options Hash (access):

  • :client_id (String)
  • :private_key (String)

Returns:



40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
 
# File 'lib/groupdocs/signature/envelope.rb', line 40

def self.all!(options = {}, access = {})
  status_id = options.delete(:status_id)
  options[:statusId] = status_id if status_id

  api = Api::Request.new do |request|
    request[:access] = access
    request[:method] = :GET
    request[:path] = '/signature/{{client_id}}/envelopes'
  end
  api.add_params(options)
  json = api.execute!

  json[:envelopes].map do |envelope|
    new(envelope)
  end
end

.for_me!(options = {}, access = {}) ⇒ Array<GroupDocs::Signature::Envelope>

Returns a list of all envelopes where user is recipient.

Parameters:

  • options (Hash) (defaults to: {}) —

    Hash of options

  • access (Hash) (defaults to: {}) —

    Access credentials

Options Hash (options):

  • :page (Integer) —

    Page to start with

  • :records (Integer) —

    How many items to list

  • :statusId (Integer) —

    Filter by status identifier

Options Hash (access):

  • :client_id (String)
  • :private_key (String)

Returns:



69
70
71
72
73
74
75
76
77
78
79
80
81
 
# File 'lib/groupdocs/signature/envelope.rb', line 69

def self.for_me!(options = {}, access = {})
  api = Api::Request.new do |request|
    request[:access] = access
    request[:method] = :GET
    request[:path] = '/signature/{{client_id}}/envelopes/recipient'
  end
  api.add_params(options)
  json = api.execute!

  json[:envelopes].map do |envelope|
    new(envelope)
  end
end

Instance Method Details

#add_recipient!(recipient, access = {}) ⇒ Object

Adds recipient to envelope.

Examples:

roles = GroupDocs::Signature::Role.get!
envelope = GroupDocs::Signature::Envelope.get!("g94h5g84hj9g4gf23i40j")
recipient = GroupDocs::Signature::Recipient.new
recipient.email = '[email protected]'
recipient.first_name = 'John'
recipient.last_name = 'Smith'
recipient.role_id = roles.detect { |role| role.name == "Signer" }.id
envelope.add_recipient! recipient

Parameters:

Options Hash (access):

  • :client_id (String)
  • :private_key (String)

Raises:

  • (ArgumentError) —

    if recipient is not GroupDocs::Signature::Recipient



129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
 
# File 'lib/groupdocs/signature/envelope.rb', line 129

def add_recipient!(recipient, access = {})
  recipient.is_a?(GroupDocs::Signature::Recipient) or raise ArgumentError,
    "Recipient should be GroupDocs::Signature::Recipient object, received: #{recipient.inspect}"

  api = Api::Request.new do |request|
    request[:access] = access
    request[:method] = :POST
    request[:path] = "/signature/{{client_id}}/envelopes/#{id}/recipient"
  end
  api.add_params(email:     recipient.email,
                 firstname: recipient.first_name,
                 lastname:  recipient.last_name,
                 role:      recipient.role_id,
                 order:     recipient.order)
  api.execute!
end

#archive!(access = {}) ⇒ Object

Archives completed envelope.

Parameters:

  • access (Hash) (defaults to: {}) —

    Access credentials

Options Hash (access):

  • :client_id (String)
  • :private_key (String) 


352
353
354
355
356
357
358
 
# File 'lib/groupdocs/signature/envelope.rb', line 352

def archive!(access = {})
  Api::Request.new do |request|
    request[:access] = access
    request[:method] = :PUT
    request[:path] = "/signature/{{client_id}}/envelopes/#{id}/archive"
  end.execute!
end

#decline!(recipient, access = {}) ⇒ Object

Declines envelope.

Parameters:

Options Hash (access):

  • :client_id (String)
  • :private_key (String)

Raises:

  • (ArgumentError) —

    if recipient is not GroupDocs::Signature::Recipient



275
276
277
278
279
280
281
282
283
284
 
# File 'lib/groupdocs/signature/envelope.rb', line 275

def decline!(recipient, access = {})
  recipient.is_a?(GroupDocs::Signature::Recipient) or raise ArgumentError,
    "Recipient should be GroupDocs::Signature::Recipient object, received: #{recipient.inspect}"

  Api::Request.new do |request|
    request[:access] = access
    request[:method] = :PUT
    request[:path] = "/signature/{{client_id}}/envelopes/#{id}/recipient/#{recipient.id}/decline"
  end.execute!
end

#fill_field!(value, field, document, recipient, access = {}) ⇒ GroupDocs::Signature::Field

Fills field with value.

Value differs depending on field type. See examples below.

Examples:

Fill single line field

envelope = GroupDocs::Signature::Envelope.get!("g94h5g84hj9g4gf23i40j")
document = envelope.documents!.first
recipient = envelope.recipients!.first
field = envelope.fields!(document, recipient).first
envelope.fill_field! "my_data", field, document, recipient

Fill signature field

envelope = GroupDocs::Signature::Envelope.get!("g94h5g84hj9g4gf23i40j")
document = envelope.documents!.first
recipient = envelope.recipients!.first
field = envelope.fields!(document, recipient).first
signature = GroupDocs::Signature.get!.first
envelope.fill_field! signature, field, document, recipient

Fill checkbox field

envelope = GroupDocs::Signature::Envelope.get!("g94h5g84hj9g4gf23i40j")
document = envelope.documents!.first
recipient = envelope.recipients!.first
field = envelope.fields!(document, recipient).first
envelope.fill_field! false, field, document, recipient

Parameters:

Options Hash (access):

  • :client_id (String)
  • :private_key (String)

Returns:

Raises:

  • (ArgumentError) —

    if field is not GroupDocs::Signature::Field

  • (ArgumentError) —

    if document is not GroupDocs::Document

  • (ArgumentError) —

    if recipient is not GroupDocs::Signature::Recipient



217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
 
# File 'lib/groupdocs/signature/envelope.rb', line 217

def fill_field!(value, field, document, recipient, access = {})
  field.is_a?(GroupDocs::Signature::Field) or raise ArgumentError,
    "Field should be GroupDocs::Signature::Field object, received: #{field.inspect}"
  document.is_a?(GroupDocs::Document) or raise ArgumentError,
    "Document should be GroupDocs::Document object, received: #{document.inspect}"
  recipient.is_a?(GroupDocs::Signature::Recipient) or raise ArgumentError,
    "Recipient should be GroupDocs::Signature::Recipient object, received: #{recipient.inspect}"

  api = Api::Request.new do |request|
    request[:access] = access
    request[:method] = :PUT
    request[:path] = "/signature/{{client_id}}/envelopes/#{id}/documents/#{document.file.guid}/recipient/#{recipient.id}/field/#{field.id}"
  end

  type = field.field_type
  if type == :signature && value.is_a?(GroupDocs::Signature)
    api.add_params(signatureId: value.id)
  else
    if type == :checkbox
      value = (value ? 'on' : 'off')
    end
    api.options[:request_body] = value
    api.options[:plain] = true
  end

  json = api.execute!
  Signature::Field.new(json[:field])
end

#logs!(access = {}) ⇒ Array<GroupDocs::Signature::Envelope::Log>

Returns a list of audit logs.

Parameters:

  • access (Hash) (defaults to: {}) —

    Access credentials

Options Hash (access):

  • :client_id (String)
  • :private_key (String)

Returns:



318
319
320
321
322
323
324
325
326
327
328
 
# File 'lib/groupdocs/signature/envelope.rb', line 318

def logs!(access = {})
  json = Api::Request.new do |request|
    request[:access] = access
    request[:method] = :GET
    request[:path] = "/signature/{{client_id}}/envelopes/#{id}/logs"
  end.execute!

  json[:logs].map do |log|
    Log.new(log)
  end
end

#modify_recipient!(recipient, access = {}) ⇒ Object

Modify recipient of envelope.

Examples:

envelope = GroupDocs::Signature::Envelope.get!("g94h5g84hj9g4gf23i40j")
recipient = envelope.recipients!.first
recipient.first_name = 'Johnny'
envelope.modify_recipient! recipient

Parameters:

Options Hash (access):

  • :client_id (String)
  • :private_key (String)

Raises:

  • (ArgumentError) —

    if recipient is not GroupDocs::Signature::Recipient



161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
 
# File 'lib/groupdocs/signature/envelope.rb', line 161

def modify_recipient!(recipient, access = {})
  recipient.is_a?(GroupDocs::Signature::Recipient) or raise ArgumentError,
    "Recipient should be GroupDocs::Signature::Recipient object, received: #{recipient.inspect}"

  api = Api::Request.new do |request|
    request[:access] = access
    request[:method] = :PUT
    request[:path] = "/signature/{{client_id}}/envelopes/#{id}/recipient/#{recipient.id}"
  end
  api.add_params(email:     recipient.email,
                 firstname: recipient.first_name,
                 lastname:  recipient.last_name,
                 role:      recipient.role_id,
                 order:     recipient.order)
  api.execute!
end

#restart!(access = {}) ⇒ Object

Restarts expired envelope.

Parameters:

  • access (Hash) (defaults to: {}) —

    Access credentials

Options Hash (access):

  • :client_id (String)
  • :private_key (String) 


367
368
369
370
371
372
373
 
# File 'lib/groupdocs/signature/envelope.rb', line 367

def restart!(access = {})
  Api::Request.new do |request|
    request[:access] = access
    request[:method] = :PUT
    request[:path] = "/signature/{{client_id}}/envelopes/#{id}/restart"
  end.execute!
end

#send!(access = {}) ⇒ Object

Sends envelope.

Parameters:

  • access (Hash) (defaults to: {}) —

    Access credentials

Options Hash (access):

  • :client_id (String)
  • :private_key (String) 


337
338
339
340
341
342
343
 
# File 'lib/groupdocs/signature/envelope.rb', line 337

def send!(access = {})
  Api::Request.new do |request|
    request[:access] = access
    request[:method] = :PUT
    request[:path] = "/signature/{{client_id}}/envelopes/#{id}/send"
  end.execute!
end

#sign!(recipient, access = {}) ⇒ Object

Signs envelope.

Parameters:

Options Hash (access):

  • :client_id (String)
  • :private_key (String)

Raises:

  • (ArgumentError) —

    if recipient is not GroupDocs::Signature::Recipient



255
256
257
258
259
260
261
262
263
264
 
# File 'lib/groupdocs/signature/envelope.rb', line 255

def sign!(recipient, access = {})
  recipient.is_a?(GroupDocs::Signature::Recipient) or raise ArgumentError,
    "Recipient should be GroupDocs::Signature::Recipient object, received: #{recipient.inspect}"

  Api::Request.new do |request|
    request[:access] = access
    request[:method] = :PUT
    request[:path] = "/signature/{{client_id}}/envelopes/#{id}/recipient/#{recipient.id}/sign"
  end.execute!
end

#signed_documents!(path, access = {}) ⇒ String

Downloads all signed documents as ZIP file to given pat.

Parameters:

  • path (String) —

    Directory to download file to

  • access (Hash) (defaults to: {}) —

    Access credentials

Options Hash (access):

  • :client_id (String)
  • :private_key (String)

Returns:

  • (String) —

    path to file



295
296
297
298
299
300
301
302
303
304
305
306
307
308
 
# File 'lib/groupdocs/signature/envelope.rb', line 295

def signed_documents!(path, access = {})
  response = Api::Request.new do |request|
    request[:access] = access
    request[:method] = :DOWNLOAD
    request[:path] = "/signature/{{client_id}}/envelopes/#{id}/documents/get"
  end.execute!

  filepath = "#{path}/#{name}.zip"
  Object::File.open(filepath, 'w') do |file|
    file.write(response)
  end

  filepath
end