Class: GroupDocs::Signature::Envelope

Inherits:
Api::Entity show all
Extended by:
ResourceMethods
Includes:
Api::Helpers::SignaturePublic, 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,
  :scheduled   => 99,
}

Instance Attribute Summary collapse

Attributes included from EntityFields

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

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!, #assign_field!, #delete_field!, #delete_field_location!, #fields!, #modify_field!, #modify_field_location!

Methods included from EntityMethods

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

Methods included from Api::Helpers::Accessor

#alias_accessor

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 



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

def creationDateTime
  @creationDateTime
end

#envelopeExpireTime ⇒ Object 



92
93
94
 
# File 'lib/groupdocs/signature/envelope.rb', line 92

def envelopeExpireTime
  @envelopeExpireTime
end

#isDemo ⇒ Object 



94
95
96
 
# File 'lib/groupdocs/signature/envelope.rb', line 94

def isDemo
  @isDemo
end

#status ⇒ Symbol

Converts status to human-readable format.

Returns:

  • (Symbol) 


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

def status
  @status
end

#statusDateTime ⇒ Object 



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

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:



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

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:



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

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



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

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) 


440
441
442
443
444
445
446
 
# File 'lib/groupdocs/signature/envelope.rb', line 440

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



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

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

#delegate_recipient!(old, new, access = {}) ⇒ Object

Delegates recipient to another one.

Examples:

envelope = GroupDocs::Signature::Envelope.get!("g94h5g84hj9g4gf23i40j")
old = envelope.recipients!.first
old.first_name = 'Johnny'
new = GroupDocs::Signature::Recipient.new
new.email = '[email protected]'
new.first_name = 'John'
new.last_name = 'Smith'
envelope.delegate_recipient! old, new

Parameters:

Options Hash (access):

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

Raises:

  • (ArgumentError) —

    if old recipient is not GroupDocs::Signature::Recipient

  • (ArgumentError) —

    if new recipient is not GroupDocs::Signature::Recipient



201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
 
# File 'lib/groupdocs/signature/envelope.rb', line 201

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

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

#fill_field!(value, field, document, recipient, options = {}, 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 (options):

  • :public (Boolean) —

    Defaults to false

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



259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
 
# File 'lib/groupdocs/signature/envelope.rb', line 259

def fill_field!(value, field, document, recipient, options = {}, 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}"

  client_id = client_id(options[:public])
  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:



401
402
403
404
405
406
407
408
409
410
411
 
# File 'lib/groupdocs/signature/envelope.rb', line 401

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



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

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) 


455
456
457
458
459
460
461
 
# File 'lib/groupdocs/signature/envelope.rb', line 455

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!(webhook = nil, access = {}) ⇒ Object

Sends envelope.

Parameters:

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

    URL to be hooked after envelope is completed

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

    Access credentials

Options Hash (access):

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


421
422
423
424
425
426
427
428
429
430
431
 
# File 'lib/groupdocs/signature/envelope.rb', line 421

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

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

Signs envelope.

Parameters:

Options Hash (options):

  • :public (Boolean) —

    Defaults to false

Raises:

  • (ArgumentError) —

    if recipient is not GroupDocs::Signature::Recipient



300
301
302
303
304
305
306
307
308
309
310
 
# File 'lib/groupdocs/signature/envelope.rb', line 300

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

  client_id = client_id(options[:public])
  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_document!(document, path, access = {}) ⇒ String

Downloads signed document to given path.

Parameters:

  • document (GroupDocs::Document) —

    Signed document

  • 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



374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
 
# File 'lib/groupdocs/signature/envelope.rb', line 374

def signed_document!(document, path, access = {})
  document.is_a?(GroupDocs::Document) or raise ArgumentError,
    "Document should be GroupDocs::Document object, received: #{document.inspect}"

  response = Api::Request.new do |request|
    request[:access] = access
    request[:method] = :DOWNLOAD
    request[:path] = "/signature/{{client_id}}/envelopes/#{id}/document/#{document.file.guid}"
  end.execute!

  filepath = "#{path}/#{name}.pdf"

  Object::File.open(filepath, 'wb') do |file|
    file.write(response)
  end

  filepath
end

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

Downloads signed documents to given path. If there is only one file in envelope, it’s saved as PDF. If there are two or more files in envelope, it’s saved as ZIP.

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



343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
 
# File 'lib/groupdocs/signature/envelope.rb', line 343

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}."
  if documents!.size == 1
    filepath << 'pdf'
  else
    filepath << 'zip'
  end

  Object::File.open(filepath, 'wb') do |file|
    file.write(response)
  end

  filepath
end