Module: RightSignature::Template

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

Instance Method Summary collapse

Methods included from Helpers

#array_to_acceptable_names_hash

Instance Method Details

#generate_build_url(options = {}) ⇒ Object

Creates a URL that give person ability to create a template in your account.

  • options: optional options for redirected person

    • callback_location: URI encoded URL that specifies the location we will POST a callback notification to when the template has been created.

    • redirect_location: A URI encoded URL that specifies the location we will redirect the user to, after they have created a template.

    • tags: tags to add to the template. an array of ‘tag_name’ (for simple tag) or => ‘value’ (for tuples pairs)

      Ex. ['created_from_api', {"user_id" => "123"}]

    • acceptable_role_names: The user creating the Template will be forced to select one of the values provided.

      There will be no free-form name entry when adding roles to the Template. An array of strings.
Ex. ["Employee", "Employeer"]

    • acceptable_merge_field_names: The user creating the Template will be forced to select one of the values provided.

      There will be no free-form name entry when adding merge fields to the Template.
Ex. ["Location", "Tax ID", "Company Name"]



213
214
215
216
217
218
219
220
221
222
223
224
225
226
 
# File 'lib/rightsignature/template.rb', line 213

def generate_build_url(options={})
  xml_hash = {:template => options}
  xml_hash[:template][:tags] = TagsHelper.array_to_xml_hash(options[:tags]) if options[:tags]

  [:acceptable_merge_field_names, :acceptable_role_names].each do |option|
    xml_hash[:template][option] = array_to_acceptable_names_hash(options[option]) if options[option]
  end

  response = post "/api/templates/generate_build_token.xml", xml_hash

  redirect_token = response["token"]["redirect_token"]

  "#{site}/builder/new?rt=#{redirect_token}"
end

#prefill(guid, subject, roles, options = {}) ⇒ Object

Prefills template. Should use a prepackaged template first.

  • guid: templates guid. Ex. a_1_zcfdidf8fi23

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

  • roles: Recipients of the document, should be an array of role names and emails in a hash with keys as role_names.

    Ex. [{"Employee" => {:name => "John Employee", :email => "[email protected]"}}]
  is equivalent to
    <role role_name="Employee">
      <name>John Employee</name>
      <email>[email protected]</email>
    </role>

  • options: other optional values

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

    • merge_fields: document merge fields, should be an array of merge_field_values in a hash with the merge_field_name.

      Ex. [{"Salary" => "$1,000,000"}]
  is equivalent to
    <merge_field merge_field_name="Salary">
    <value>$1,000,000</value>
    </merge_field>

    • 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"

Ex. call with all options used

@rs_connection.prefill(
  "a_1_zcfdidf8fi23",
  "Your Employee Handbook",
  [{"employee" => {:name => "John Employee", :email => "[email protected]"}}],
  {
    :description => "Please read over the handbook and sign it.",
    :merge_fields => [
      { "Department" => "Fun and games" },
      { "Salary" => "$1,000,000" }
    ],
    :expires_in => 5,
    :tags => [
      {:name => 'sent_from_api'},
      {:name => 'user_id', :value => '32'}
    ],
    :redirect_location => "http://yoursite/redirect",
    :callback_location => "http://yoursite/callback"
  })



88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
 
# File 'lib/rightsignature/template.rb', line 88

def prefill(guid, subject, roles, options={})
  use_merge_field_ids = options.delete(:use_merge_field_ids)
  xml_hash = {
    :template => {
      :guid => guid,
      :action => "prefill",
      :subject => subject
    }.merge(options)
  }

  xml_hash[:template][:roles] = RolesHelper.array_to_xml_hash(roles)

  # Optional arguments
  xml_hash[:template][:merge_fields] = MergeFieldsHelper.array_to_xml_hash(options[:merge_fields], use_merge_field_ids) if options[:merge_fields]
  xml_hash[:template][:tags] = TagsHelper.array_to_xml_hash(options[:tags]) if options[:tags]

  post "/api/templates.xml", xml_hash
end

#prepackage(guid) ⇒ Object

Clones a template so it can be used for sending. Always first step in sending a template.

  • guid: templates guid. Ex. a_1_zcfdidf8fi23



41
42
43
 
# File 'lib/rightsignature/template.rb', line 41

def prepackage(guid)
  post "/api/templates/#{guid}/prepackage.xml", {}
end

#prepackage_and_send(guid, roles, options = {}) ⇒ Object

Prepackages and sends template.

  • guid: templates guid. Ex. a_1_zcfdidf8fi23

  • roles: Recipients of the document, should be an array of role names and emails in a hash with keys as role_names.

    Ex. [{"Employee" => {:name => "John Employee", :email => "[email protected]"}}]
  is equivalent to
    <role role_name="Employee">
      <name>John Employee</name>
      <email>[email protected]</email>
    </role>

  • options: other optional values

    • subject: subject of the document that’ll appear in email. Defaults to template’s subject

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

    • merge_fields: document merge fields, should be an array of merge_field_values in a hash with the merge_field_name.

      Ex. [{"Salary" => "$1,000,000"}]
  is equivalent to
    <merge_field merge_field_name="Salary">
    <value>$1,000,000</value>
    </merge_field>

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

    • tags: document tags, an array of => ‘tag_name’ (for simple tag) or => ‘tag_name’, :value => ‘value’ (for tuples pairs)

      Ex. [{:name => 'sent_from_api'}, {:name => "user_id", :value => "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"

Ex. call with all options used

@rs_connection.prepackage_and_send(
  "a_1_zcfdidf8fi23",
  "Your Employee Handbook",
  [{"employee" => {:name => "John Employee", :email => "[email protected]"}}],
  {
    :description => "Please read over the handbook and sign it.",
    :merge_fields => [
      { "Department" => "Fun and games" },
      { "Salary" => "$1,000,000" }
    ],
    :expires_in => 5,
    :tags => [
      {:name => 'sent_from_api'},
      {:name => 'user_id', :value => '32'}
    ],
    :callback_location => "http://yoursite/callback"
  })



149
150
151
152
153
 
# File 'lib/rightsignature/template.rb', line 149

def prepackage_and_send(guid, roles, options={})
  response = prepackage(guid)
  new_guid = response["template"]["guid"]
  send_template(new_guid, options.delete(:subject) || response["template"]["subject"], roles, options)
end

#send_as_embedded_signers(guid, recipients, options = {}) ⇒ Object

Sends template with all roles as embedded signers and returns an array of hashes with :name and :url for each signer link.

  • guid: templates guid. Ex. a_1_zcfdidf8fi23

  • roles: Recipients of the document, should be an array of role names in a hash with keys as role_names.

    Ex. [{"Employee" => {:name => "John Employee"}]
  is equivalent to
    <role role_name="Employee">
      <name>John Employee</name>
      <email>[email protected]</email>
    </role>

  • options: other optional values

    • subject: subject of the document that’ll appear in email. Defaults to Template’s subject

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

    • merge_fields: document merge fields, should be an array of merge_field_values in a hash with the merge_field_name.

      Ex. [{"Salary" => "$1,000,000"}]
  is equivalent to
    <merge_field merge_field_name="Salary">
    <value>$1,000,000</value>
    </merge_field>

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

    • tags: document tags, an array of => ‘tag_name’ (for simple tag) or => ‘tag_name’, :value => ‘value’ (for tuples pairs)

      Ex. [{:name => 'sent_from_api'}, {:name => "user_id", :value => "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"

    • redirect_location: A URI encoded URL that specifies the location for the signing widget to redirect the user to after it is signed.

      Ex. "http://yoursite/thanks_for_signing"

Ex. call with all options used

@rs_connection.send_as_embedded_signers(
  "a_1_zcfdidf8fi23",
  "Your Employee Handbook",
  [{"employee" => {:name => "John Employee", :email => "[email protected]"}}],
  {
    :description => "Please read over the handbook and sign it.",
    :merge_fields => [
      { "Department" => "Fun and games" },
      { "Salary" => "$1,000,000" }
    ],
    :expires_in => 5,
    :tags => [
      {:name => 'sent_from_api'},
      {:name => 'user_id', :value => '32'}
    ],
    :redirect_location => "http://yoursite/redirect_from_signing"
  })



272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
 
# File 'lib/rightsignature/template.rb', line 272

def send_as_embedded_signers(guid, recipients, options={})
  redirect_location = options.delete(:redirect_location)

  response = prepackage(guid)
  template = response["template"]

  recipients.each do |role_hash|
    key, value = role_hash.first
    role_hash[key][:email] = "[email protected]" unless role_hash[key]["email"] || role_hash[key][:email]
  end

  response = send_template(template["guid"], options[:subject] || template["subject"], recipients, options)
  document_guid = response["document"]["guid"]

  get_document_signer_links_for(document_guid, redirect_location)
end

#send_template(guid, subject, roles, options = {}) ⇒ Object

Sends template. Should use a prepackaged template first. Easier to use prepackage_and_send for most cases.

  • guid: templates guid. Ex. a_1_zcfdidf8fi23

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

  • roles: Recipients of the document, should be an array of role names and emails in a hash with keys as role_names.

    Ex. [{"Employee" => {:name => "John Employee", :email => "[email protected]"}}]
  is equivalent to
    <role role_name="Employee">
      <name>John Employee</name>
      <email>[email protected]</email>
    </role>

  • options: other optional values

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

    • merge_fields: document merge fields, should be an array of merge_field_values in a hash with the merge_field_name.

      Ex. [{"Salary" => "$1,000,000"}]
  is equivalent to
    <merge_field merge_field_name="Salary">
    <value>$1,000,000</value>
    </merge_field>

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

    • tags: document tags, an array of => ‘tag_name’ (for simple tag) or => ‘tag_name’, :value => ‘value’ (for tuples pairs)

      Ex. [{:name => 'sent_from_api'}, {:name => "user_id", :value => "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"

Ex. call with all options used

@rs_connection.send_template(
  "a_1_zcfdidf8fi23",
  "Your Employee Handbook",
  [{"employee" => {:name => "John Employee", :email => "[email protected]"}}],
  {
    :description => "Please read over the handbook and sign it.",
    :merge_fields => [
      { "Department" => "Fun and games" },
      { "Salary" => "$1,000,000" }
    ],
    :expires_in => 5,
    :tags => [
      {:name => 'sent_from_api'},
      {:name => 'user_id', :value => '32'}
    ],
    :callback_location => "http://yoursite/callback"
  })



197
198
199
 
# File 'lib/rightsignature/template.rb', line 197

def send_template(guid, subject, roles, options={})
  prefill(guid, subject, roles, options.merge({:action => 'send'}))
end

#template_details(guid) ⇒ Object

Gets template details

  • guid: templates guid. Ex. a_1_zcfdidf8fi23



35
36
37
 
# File 'lib/rightsignature/template.rb', line 35

def template_details(guid)
  get "/api/templates/#{guid}.xml", {}
end

#templates_list(options = {}) ⇒ Object

List Templates with optional filters

  • Options: (optional) Hash of filters to use

    • page: page number

    • per_page: number of templates to return per page. API only supports 10, 20, 30, 40, or 50. Default is 10.

    • tags: filter templates by given tags. Array of strings, for name/value tags colon (:) should separate name and value. Ex. “single_tag,tag_key:tag_value” would find templates with ‘single_tag’ and the name/value of ‘tag_key’ with value ‘tag_value’.

    • search: term to search for in templates.

Ex.

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



24
25
26
27
28
29
30
31
 
# File 'lib/rightsignature/template.rb', line 24

def templates_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
  get "/api/templates.xml", options
end

#trash_template(guid) ⇒ Object

Deletes a template

  • guid: Document GUID

Ex. Delete template GUID123

@rs_connection.trash_template("GUID123")



295
296
297
 
# File 'lib/rightsignature/template.rb', line 295

def trash_template(guid)
  delete "/api/templates/#{guid}.xml"
end