The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
WebService-JotForm-0.020
River stage zero No dependents
1 ++
/ WebService::JotForm

NAME

WebService::JotForm - Perl interface to JotForm's API -- currently only the read operations are fully supported.

Support for create, update, and delete operations are beginning to be added in this and future releases.

VERSION

Version 0.020

SYNOPSIS

        my $jotform = WebService::JotForm->new( apiKey => $apiKey);

        my $forms = $jotform->get_user_forms();

        # Show form details associated with our account

        foreach my $form (@{$forms->{content}}) {
                print "Form $form->{id} - $form->{title} - $form->{url} - $form->{last_submission}\n";
        }

        my $form_id = "42";

        my $submissions = $jotform->get_form_submissions($form_id);

        # Loop through all submissions to our form and print out submission created_at and ip

        foreach my $sub(@{$submissions->{content}}) {
                print "$sub->{created_at} $sub->{ip}\n";
        }

DESCRIPTION

This is a thin wrapper around the JotForm API. All results are what's returned by the JotForm API, with the JSON being converted into Perl data structures.

You need a JotForm API key to use this module. The easiest way to get an apiKey is just to login to JotForm and then go to http://www.jotform.com/myaccount/api. From there create a token (or use an existing one). You can set whether it's a read-only or full-access token.

More information on tokens is available in the JotForm API Documentation

METHODS

new(%params)

Create a new WebService::JotForm object with hash parameter

        my $jotform = WebService::JotForm->new(
                apiKey => '1234567890abcdef'
        );

Accepts the following parameters:

  • apiKey

    Required parameter. JotForm apiKey

  • apiBase

    Optional parameter - defaults to: 'https://api.jotform.com'

  • apiVersion

    Optional parameter - defaults to 'v1'

  • agent

    Agent that acts like LWP::UserAgent used for making requests -- module defaults to creating its own if none is provide

get_user()

        $jotform->get_user();

Get user account details for this JotForm user. Including user account type, avatar URL, name, email, website URL and account limits.

        my $user = $jotform->get_user();

get_user_usage()

        $jotform->get_user_usage();

Get number of form submissions received this month. Also, get number of SSL form submissions, payment form submissions and upload space used by user.

get_user_submissions($params)

        $jotform->get_user_submissions($params);

Get a list of all submissions for all forms on this account. The answers array has the submission data. Created_at is the date of the submission. Optional paramaters

offset
        Example: 20
limit
        Example: 20
filter
        Example: {"new":"1"} or {"created_at:gt":"2013-01-01 00:00:00"}
orderby
        Example: created_at

get_user_subusers()

        $jotform->get_user_subusers();

Get a list of sub users for this accounts and list of forms and form folders with access privileges.

get_user_folders()

        $jotform->get_user_folders();

Get a list of form folders for this account. Returns name of the folder and owner of the folder for shared folders.

get_user_reports()

        $jotform->get_user_reports();

List of URLS for reports in this account. Includes reports for all of the forms. ie. Excel, CSV, printable charts, embeddable HTML tables.

register_user()

        $jotform->register_user($params);

        $jotform->register_user({ username => $username, password => $pw, email => $email });

Register a new JotForm account with username, password and email

login_user()

        $jotform->register_user($params);

        $jotform->register_user({ username => $username, password => $pw });

Login user with given credentials - accepts username, password, and optionally appName, and access

get_user_logout()

        $jotform->get_user_logout();

Logout user

get_user_settings()

        $jotform->get_user_settings();

Get user's time zone and language.

update_user_settings()

        $jotform->update_user_settings($params);
        
        $jotform->update_user_settings({ email => $updated_email });

Update user's settings like time zone and language. Optional fields: name, email, website, time_zone, company, securityQuestion, securityAnswer, industry

get_user_history()

        $jotform->get_user_history();

User activity log about things like forms created/modified/deleted, account logins and other operations.

get_user_forms($params)

        $jotform->get_user_forms($params);

Get a list of forms for this account. Includes basic details such as title of the form, when it was created, number of new and total submissions.

TODO -- document additionsal optional params

create_forms($params);

        $jotform->create_forms($params);

Add new forms with questions, properties and email settings.

create_form($params);

        $jotform->create_form($params);

Add new form with questions, properties and email settings.

get_form($id)

        $jotform->get_form($id);

Get basic information about a form. Use get_form_questions($id) to get the list of questions.

clone_form($id)

        $jotform->clone_form($id);

Clone a given form

create_form_question($id, $question)

        $jotform->create_form_question($id, $question)

        Add a new question to a form, takes an id for the form as a parameter, and then a hasref of key/values for the question fields

edit_form_question($form_id, $qid, $question);

        $jotform->edit_form_question($form_id, $qid, $question);

Edit a question property or add a new one. Form questions might have various properties. Examples: Is it required? Are there any validations such as 'numeric only'?

set_form_properties($form_id, $params)

        $jotform->set_form_properties($form_id, $params);
        
        $jotform->set_form_properties($form_id, { formWidth => 555 });

Add or edit properties of a specific form

get_form_questions($id)

        $jotform->get_form_questions($id);

        Get a list of all questions on a form. Type describes question field type. Order is the question order in the form. Text field is the question label.

get_form_question($form_id, $qid)

        $jotform->get_form_question($form_id, $qid);

        Get Details About a Question

get_form_properties($id,$key)

        $jotform->get_form_properties($id);
        
        $jotform->get_form_properties($id,$key);

        Get a list of all properties on a form.

get_form_reports($id)

        $jotform->getFormReports($id);

        Get all the reports of a specific form.

create_form_report($form_id, { title => $title, list_type => $list_type });

        $jotform->create_form_report($form_id, { title => $title, list_type => "csv" });
        $jotform->create_form_report($form_id, { title => $title, list_type => "csv", "fields=ip,dt,1" });

        Create new report of a form with intended fields, type and title.

get_form_files($id)

        $jotform->get_form_files($id);

        List of files uploaded on a form. Here is how you can access a particular file: http://www.jotform.com/uploads/{username}/{form-id}/{submission-id}/{file-name}. Size and file type is also included.

get_form_webhooks($id)

        $jotform->get_form_webhooks($id)

        Webhooks can be used to send form submission data as an instant notification. Returns list of webhooks for this form.

create_form_webhook($form_id, $url)

        $jotform->create_form_webhook($form_id, $url);

        Webhooks can be used to send form submission data as an instant notification.  Add a new webhook that receives submission data for a given form

get_form_submissions($id)

        $jotform->get_form_submissions($id, $params);

        List of form reponses. Fields array has the submitted data. Created_at is the date of the submission.

get_submission($id)

        $jotform->get_submission($id);

        Similar to get_form_submissions($id) But only get a single submission, based on submission id

get_report($id)

        $jotform->get_report($id);

        Get more information about a data report.

get_folder($id)

        $jotform->get_folder($id)

        Get a list of forms in a folder, and other details about the form such as folder color.

get_system_plan($plan_name)

        $jotform->get_system_plan($plan_name)

        Get limit and prices of a plan.

AUTHOR

Tim Vroom, <vroom at blockstackers.com>

BUGS

Please report any bugs or feature requests to bug-webservice-jotform at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=WebService-JotForm. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

SUPPORT

You can find documentation for this module with the perldoc command.

    perldoc WebService::JotForm

You can also look for information at:

ACKNOWLEDGEMENTS

LICENSE AND COPYRIGHT

Copyright 2014 Tim Vroom.

This program is free software; you can redistribute it and/or modify it under the terms of the the Artistic License (2.0). You may obtain a copy of the full license at:

http://www.perlfoundation.org/artistic_license_2_0

Any use, modification, and distribution of the Standard or Modified Versions is governed by this Artistic License. By using, modifying or distributing the Package, you accept this license. Do not use, modify, or distribute the Package, if you do not accept this license.

If your Modified Version has been derived from a Modified Version made by someone other than you, you are nevertheless required to ensure that your Modified Version complies with the requirements of this license.

This license does not grant you the right to use any trademark, service mark, tradename, or logo of the Copyright Holder.

This license includes the non-exclusive, worldwide, free-of-charge patent license to make, have made, use, offer to sell, sell, import and otherwise transfer the Package with respect to any patent claims licensable by the Copyright Holder that are necessarily infringed by the Package. If you institute patent litigation (including a cross-claim or counterclaim) against any party alleging that the Package constitutes direct or contributory patent infringement, then this Artistic License to you shall terminate on the date that such litigation is filed.

Disclaimer of Warranty: THE PACKAGE IS PROVIDED BY THE COPYRIGHT HOLDER AND CONTRIBUTORS "AS IS' AND WITHOUT ANY EXPRESS OR IMPLIED WARRANTIES. THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT ARE DISCLAIMED TO THE EXTENT PERMITTED BY YOUR LOCAL LAW. UNLESS REQUIRED BY LAW, NO COPYRIGHT HOLDER OR CONTRIBUTOR WILL BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL DAMAGES ARISING IN ANY WAY OUT OF THE USE OF THE PACKAGE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.