class Formstack::API
Constants
- FIELD_TYPES
Public Class Methods
new(access_token)
click to toggle source
# File lib/formstack/api.rb, line 32 def initialize(access_token) @access_token = access_token @api_url = 'https://www.formstack.com/api/v2/' end
Private Class Methods
add_field_data(arguments, field_ids, field_values)
click to toggle source
# File lib/formstack/api.rb, line 282 def self.add_field_data(arguments, field_ids, field_values) if field_ids.empty? raise 'There must be a one-to-one relationship between Field IDs and their values' if field_ids.size != field_values.size end field_ids.each_with_index do |id, i| raise 'Field IDs must be numeric' unless id.is_a? Numeric arguments["field_#{field_ids[i]}"] = field_values[i] end arguments end
clean_arguments(args)
click to toggle source
# File lib/formstack/api.rb, line 296 def self.clean_arguments(args) arguments = {} args.each_pair do |key, value| arguments[key] = value unless value == '' end arguments end
Public Instance Methods
copy_form(form_id)
click to toggle source
# File lib/formstack/api.rb, line 91 def copy_form(form_id) is_numeric?(form_id) request("form/#{form_id}/copy", 'POST'); end
create_field(form_id, field_type = '', label = '', hide_label = false, description = '', use_callout = false, field_specific_attributes = [], default_value = '', options = [], options_values = [], required = false, read_only = false, hidden = false, unique = false, column_span = nil, sort = nil)
click to toggle source
# File lib/formstack/api.rb, line 249 def create_field(form_id, field_type = '', label = '', hide_label = false, description = '', use_callout = false, field_specific_attributes = [], default_value = '', options = [], options_values = [], required = false, read_only = false, hidden = false, unique = false, column_span = nil, sort = nil) is_numeric?(form_id) raise 'Provided Field Type is not in the list of known Field types' unless FIELD_TYPES.include? field_type arguments = {} arguments['field_type'] = field_type arguments['label'] = label unless label.empty? arguments['hide_label'] = 1 if hide_label arguments['description'] = description unless description.empty? arguments['description_callout'] = 1 if use_callout arguments['default_value'] = default_value unless default_value.empty? arguments['options'] = options unless options.empty? arguments['options_values'] = options_values unless options_values.empty? arguments['required'] = 1 if required arguments['read_only'] = 1 if read_only arguments['hidden'] = 1 if hidden arguments['unique'] = 1 if unique arguments['colspan'] = column_span unless column_span.nil? arguments['sort'] = sort unless sort.nil? request("form/#{form_id}/field", 'POST', { body: arguments } ) end
delete_submission(submission_id)
click to toggle source
# File lib/formstack/api.rb, line 243 def delete_submission(submission_id) raise 'Submission ID must be numeric' unless submission_id.is_a? Numeric request("submission/#{submission_id}", 'DELETE' ) end
edit_submission_data(submission_id, field_ids = [], field_values = [], timestamp = '', user_agent = '', ip_address = '', payment_status = '', read = false)
click to toggle source
# File lib/formstack/api.rb, line 210 def edit_submission_data(submission_id, field_ids = [], field_values = [], timestamp = '', user_agent = '', ip_address = '', payment_status = '', read = false) arguments = { 'timestamp' => timestamp, 'user_agent' => user_agent, 'remote_addr' => ip_address, 'payment_status' => payment_status, 'read' => read ? 1 : 0 } raise 'Submission ID must be numeric' unless submission_id.is_a? Numeric unless timestamp.empty? begin Time.parse(timestamp) rescue Exception => e raise 'You must use a valid Date/Time string formatted in YYYY-MM-DD HH:MM:SS' end end arguments = API.clean_arguments(arguments) arguments = API.add_field_data(arguments, field_ids, field_values) request("submission/#{submission_id}.json", 'PUT', { body: arguments } ) end
form_details(form_id)
click to toggle source
# File lib/formstack/api.rb, line 79 def form_details(form_id) is_numeric?(form_id) request("form/#{form_id}", 'GET'); end
form_fields(form_id)
click to toggle source
# File lib/formstack/api.rb, line 85 def form_fields(form_id) is_numeric?(form_id) request("form/#{form_id}/field.json", 'GET'); end
form_submissions(form_id, encryption_password='', min_time='', max_time='', search_fields=[], search_fields_values=[], page_number=1, per_page=25, sort='DESC', data=false, expand_data=false)
click to toggle source
# File lib/formstack/api.rb, line 97 def form_submissions(form_id, encryption_password='', min_time='', max_time='', search_fields=[], search_fields_values=[], page_number=1, per_page=25, sort='DESC', data=false, expand_data=false) is_numeric?(form_id) unless min_time.empty? begin Time.parse(min_time) rescue Exception => e raise 'Invalid value for minTime parameter' end end unless max_time.empty? begin Time.parse(max_time) rescue Exception => e raise 'Invalid value for maxTime parameter' end end raise 'You must have a one to one relationship' unless search_fields.size == search_fields_values.size search_fields.each do |id| raise 'Field IDs must be numeric' unless id.is_a? Numeric end if !per_page.is_a? Numeric raise 'The perPage value must be numeric' elsif per_page < 1 || per_page > 100 raise 'You can only retrieve a minimum of 1 and maximum of 100 submissions per request' end raise 'The pageNumber value must be numeric' unless page_number.is_a? Numeric raise 'The sort parameter must be ASC or DESC' unless sort == 'ASC' || sort == 'DESC' end_point = "form/#{form_id}/submission.json" sort.upcase! arguments = { 'encryption_password' => encryption_password, 'min_time' => min_time, 'max_time' => max_time, 'page' => page_number, 'per_page' => per_page, 'sort' => sort, 'data' => data, 'expand_data' => expand_data, } arguments.delete('data') unless data arguments.delete('expand_data') unless expand_data arguments = API.clean_arguments(arguments) search_fields.each_with_index do |field, idx| arguments["search_field_#{idx}"] = search_field_ids[idx] arguments["search_value_#{idx}"] = search_field_values[idx] end response = request(end_point, 'GET', { body: arguments }) response['submissions'] end
forms(organized_folders=false)
click to toggle source
# File lib/formstack/api.rb, line 73 def forms(organized_folders=false) organized_folders = organized_folders ? 1 : 0 response = request("form.json#{query(folders: organized_folders)}", 'GET') response['forms'] end
get_submission_details(submission_id, encryption_password = '')
click to toggle source
# File lib/formstack/api.rb, line 201 def get_submission_details(submission_id, encryption_password = '') arguments = {} arguments['encryption_password'] = encryption_password unless encryption_password.empty? raise 'Submission ID must be numeric' unless submission_id.is_a? Numeric response = request("submission/#{submission_id}.json", 'GET', arguments) end
request(end_point, verb='GET', arguments={})
click to toggle source
# File lib/formstack/api.rb, line 37 def request(end_point, verb='GET', arguments={}) arguments.merge!(headers: { "Authorization" => "Bearer #{@access_token }"}) valid_verbs = %w(GET PUT POST DELETE) if end_point.empty? raise 'Missing End Point' end verb.upcase! unless valid_verbs.include?(verb) raise 'Wrong verb' end url = "#{@api_url}#{end_point}" case verb when 'GET' response = self.class.get(url, arguments ) when 'POST' response = self.class.post(url, arguments ) when 'PUT' response = self.class.put(url, arguments ) when 'DELETE' response = self.class.delete(url, arguments ) end if response.code < 200 || response.code >= 300 raise 'Bad token' end body = JSON.parse(response.body) return body end
submit_form(form_id, field_ids = [], field_values = [], timestamp = '', user_agent = '', ip_address = '', payment_status = '', read = false)
click to toggle source
# File lib/formstack/api.rb, line 166 def submit_form(form_id, field_ids = [], field_values = [], timestamp = '', user_agent = '', ip_address = '', payment_status = '', read = false) arguments = { 'timestamp' => timestamp, 'user_agent' => user_agent, 'remote_addr' => ip_address, 'payment_status' => payment_status, 'read' => read ? 1 : 0 } is_numeric?(form_id) unless timestamp.empty? begin Time.parse(timestamp) rescue Exception => e raise 'You must use a valid Date/Time string formatted in YYYY-MM-DD HH:MM:SS' end end raise 'There must be a one-to-one relationship between Field IDs and their values' unless field_ids.size == field_values.size arguments = API.clean_arguments(arguments) arguments = API.add_field_data(arguments, field_ids, field_values) response = request("form/#{form_id}/submission.json", 'POST', { body: arguments } ) end
Private Instance Methods
is_numeric?(form_id)
click to toggle source
# File lib/formstack/api.rb, line 306 def is_numeric?(form_id) unless form_id.is_a? Numeric raise 'Form ID must be numeric' end end
query(args)
click to toggle source
# File lib/formstack/api.rb, line 312 def query(args) query = URI.encode_www_form(args) "?#{query}" end