Class: RightSignature::Template

Inherits:
Object
  • Object
show all
Extended by:
Helpers
Defined in:
lib/rightsignature/template.rb

Class Method Summary collapse

Methods included from Helpers

array_to_acceptable_names_hash

Class Method Details

.details(guid) ⇒ Object 



20
21
22
 
# File 'lib/rightsignature/template.rb', line 20

def details(guid)
  RightSignature::Connection.get "/api/templates/#{guid}.xml", {}
end

.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 {'tag_name' => 'value'} (for tuples pairs)
    Ex. ['created_from_api', {"user_id" => "123"}]
- acceptabled_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"]



156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
 
# File 'lib/rightsignature/template.rb', line 156

def generate_build_url(options={})
  xml_hash = {:template => {}}
  xml_hash[:template][:tags] = TagsHelper.array_to_xml_hash(options[:tags]) if options[:tags]
  
  [:acceptable_merge_field_names, :acceptabled_role_names].each do |option|
    xml_hash[:template][option] = array_to_acceptable_names_hash(options[option]) if options[option]
  end
  
  [:callback_location, :redirect_location].each do |other_option|
    xml_hash[:template][other_option] = options[other_option] if options[other_option]
  end

  response = RightSignature::Connection.post "/api/templates/generate_build_token.xml", xml_hash
  
  redirect_token = response["token"]["redirect_token"]
  
  "#{RightSignature::Connection.site}/builder/new?rt=#{redirect_token}"
end

.list(options = {}) ⇒ Object

List Templates and passes in optional options.

Options:
 * 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.



15
16
17
18
 
# File 'lib/rightsignature/template.rb', line 15

def list(options={})
  options[:tags] = TagsHelper.mixed_array_to_string_array(options[:tags]) if options[:tags]
  RightSignature::Connection.get "/api/templates.xml", options
end

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

Prefills template.

  • 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_name' => 'tag_value'} (for tuples pairs)
    Ex. ['sent_from_api', {"user_id" => "32"}]
- callback_url: 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

RightSignature::Template.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'}
    ],
    :callback_url => "http://yoursite/callback"
  })



71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
 
# File 'lib/rightsignature/template.rb', line 71

def prefill(guid, subject, roles, options={})
  xml_hash = {
    :template => {
      :guid => guid,
      :action => "prefill",
      :subject => subject
    }
  }
  
  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]) if options[:merge_fields]        
  xml_hash[:template][:tags] = TagsHelper.array_to_xml_hash(options[:tags]) if options[:tags]
  [:expires_in, :description, :callback_url, :action].each do |other_option|
    xml_hash[:template][other_option] = options[other_option] if options[other_option]
  end

  RightSignature::Connection.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.



25
26
27
 
# File 'lib/rightsignature/template.rb', line 25

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

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



92
93
94
95
96
 
# File 'lib/rightsignature/template.rb', line 92

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

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

Sends template.

  • 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 {:name => 'tag_name'} (for simple tag) or {:name => 'tag_name', :value => 'value'} (for tuples pairs)
    Ex. [{:name => 'sent_from_api'}, {:name => "user_id", :value => "32"}]
- callback_url: 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

RightSignature::Template.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'}
    ],
    :callback_url => "http://yoursite/callback"
  })



140
141
142
 
# File 'lib/rightsignature/template.rb', line 140

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