search

zaus / forms-3rdparty-integration

Wordpress Plugin - Forms 3rdparty Integration - a plugin to help integrate 3rdparty services with common WP Forms plugins like Contact Form 7 and Gravity Forms
http://wordpress.org/plugins/forms-3rdparty-integration/
47 stars 14 forks source link

readme

Forms: 3rd-Party Integration

(please note, the following was poorly copied from the Wordpress readme)

Contributors: zaus, atlanticbt, spkane

Donate link: http://drzaus.com/donate

Tags: contact form, form, contact form 7, CF7, gravity forms, GF, CRM, mapping, 3rd-party service, services, remote request

Requires at least: 3.0

Tested up to: 5.2.3

Stable tag: trunk

License: GPLv2 or later

Send contact form submissions from other plugins to multiple external services e.g. CRM. Configurable, custom field mapping, pre/post processing.

Description

Send Contact Form 7, Gravity Forms, or Ninja Forms Submissions to a 3rd-party Service, like a CRM. Multiple configurable services, custom field mapping. Provides hooks and filters for pre/post processing of results. Allows you to send separate emails, or attach additional results to existing emails. Comes with a couple examples of hooks for common CRMs (listrak, mailchimp, salesforce). Check out the FAQ section for add-on plugins that extend this functionality, like sending XML/SOAP posts, setting headers, and dynamic fields.

The plugin essentially makes a remote request (POST) to a service URL, passing along remapped form submission values.

Based on idea by Alex Hager "How to Integrate Salesforce in Contact Form 7".

Original plugin, Contact Form 7: 3rdparty Integration developed with the assistance of AtlanticBT. Current plugin sponsored by Stephen P. Kane Consulting. Please submit bugs / support requests to GitHub issue tracker in addition to the Wordpress Support Forums because the Forums do not send emails.

Installation

  1. Unzip, upload plugin folder to your plugins directory (/wp-content/plugins/)
  2. Make sure at least one of Contact Form 7, Gravity Forms, or Ninja Forms is installed
  3. Activate plugin
  4. Go to new admin subpage "3rdparty Services" under the CF7 "Contact" menu or Gravity Forms (or Ninja Forms) "Forms" menu and configure services + field mapping.
  5. Turn on 'debug mode' to get emailed a copy of the submission+response data, until you're satisfied everything works, then turn it off

Frequently Asked Questions

I need help / My form isn't working

Turn on 'debug mode' from the admin page to send you an email with:

Submit an issue to the GitHub issue tracker in addition to / instead of the WP Support Forums.

How do I add / configure a service?

See Screenshots for visual examples.

Essentially,

  1. Name your service.
  2. Enter the submission URL -- if your "service" provides an HTML form, you would use the form action here.
  3. Choose which forms will submit to this service ("Attach to Forms").
  4. Set the default "success condition", or leave blank to ignore (or if using post processing, see Hooks - this just looks for the provided text in the service response, and if present assumes "success"
  5. Set an optional "failure message" to show if the remote request fails. Can include the "nice explanation" as well as the original message provided by the contact form plugin.
  6. Allow hooks for further processing - unchecking it just saves minimal processing power, as it won't try to execute filters.
  7. Map your form submission values (from the CF7/GF field tags) to expected fields for your service.
    • 1:1 mapping given as the name (from the HTML input) of the CF7/GF field and the name of the 3rdparty field
    • For GF and Ninja Forms, you may map either by the field name or the field label
    • You can also provide static values by checking the "Is Value?" checkbox and providing the value in the "Form Submission Field" column.
    • The "Label" column is optional, and just provided for administrative notes, i.e. so you can remind yourself what each mapping pertains to.
  8. Add, remove, and rearrange mapping - basically just for visual clarity.
  9. Use the provided hooks (as given in the bottom of the service block).
  10. Add new services as needed, drag/drop mappings and service boxes.

How can I pre/post process the request/results?

See section Hooks. See plugin folder /3rd-parties for example code for some common CRMs, which you can either directly include or copy to your code.

I need to submit multiple values as...

If you instead need to combine/nest fields, check out Forms: 3rdparty Xpost.

How do I make a GET request instead of POST?

Since v1.7.6, it's an admin setting for GET and POST, but for anything other than those two that you'd write a hook.

from http://wordpress.org/support/topic/method-get?replies=2#post-5996489

See 'Hooks' section, #5 of http://wordpress.org/plugins/forms-3rdparty-integration/other_notes/ and the source code.

You'll need to perform wp_remote_get inside that filter and set $post_args['response_bypass'] with the response, something like:

function my_3rdparty_get_override($post_args, $service, $form) {
    $post_args['response_bypass'] = wp_remote_get($service['url'], $post_args);
    return $post_args;
}

How do I dynamically change the URL?

Use the hook Forms3rdPartyIntegration_service_filter_url.

What about Hidden Fields?

Using hidden fields can provide an easier way to include arbitrary values on a per-form basis, rather than a single "Is Value?" in the Service mapping, as you can then put your form-specific value in the hidden field, and map the hidden field name generically.

For convenience, you can install the Contact Form 7 Modules: Hidden Fields. This plugin originally included the relevant code, but it was causing issues on install, so is no longer bundled with it.

How do I export/import settings?

Use the "Forms 3rdparty Migration" plugin http://wordpress.org/plugins/forms-3rdparty-migrate/, which lets you export and import the raw settings as JSON. You can also export settings from the original plugin Contact Form 7: 3rdparty Integration and "upgrade" them for this plugin (although > 1.6.1 you will need to reselect forms). Also at https://github.com/zaus/forms-3rdparty-migrate

How do I map url parameters?

Use the "Dynamic Fields" plugin: http://wordpress.org/plugins/forms-3rdparty-dynamic-fields/ Also at https://github.com/zaus/forms-3rdparty-dynamicfields

How do I send XML/submit to SOAP?

For simple xml containers try the "Forms 3rdparty Xpost" plugin: http://wordpress.org/plugins/forms-3rd-party-xpost/ Also at https://github.com/zaus/forms-3rdparty-xpost

How do I set headers?

You can also set headers with "Forms 3rdparty Xpost" plugin: http://wordpress.org/plugins/forms-3rd-party-xpost/ Also at https://github.com/zaus/forms-3rdparty-xpost

How do I show a custom message on the confirmation screen?

The failure message is shown by default if the 3rdparty post did not succeed. You can add custom messaging to the plugin's (GF, CF7, Ninja) email or success screen response with something like:

class MyPlugin {
    public function MyPlugin() {
        add_filter('Forms3rdPartyIntegration_service', array(&$this, 'adjust_response'), 10, 2);
    }

    public function adjust_response($body, $refs) {
        // use 'attach' to inject to regular email
        // use 'message' to inject to page
        $refs['attach'] = 'custom message in email';
        $refs['message'] = 'custom message on page';
    }
}
new MyPlugin(); // attach hook

How do I conditionally submit? (if field == ...)

Use hook '...use_submission' to check the form submission (pre-mapping), making sure to pick the appropriate scenario, like:

add_filter('Forms3rdPartyIntegration_use_submission', 'f3i_conditional_submit', 10, 3);
function f3i_conditional_submit($use_this_form, $submission, $sid) {
    // if there was a specific value -- skip
    if(isset($submission['maybe-send']) && 'no' == $submission['maybe-send']) return false;
    // if there was a specific value -- use
    if(isset($submission['maybe-send']) && 'yes' == $submission['maybe-send']) return $use_this_form; // or true, i guess
    // if there was a value for it (e.g. for checkboxes) -- skip
    if(isset($submission['if-not-send'])) return false;
    // if there was a value for it (e.g. for checkboxes) -- use
    if(isset($submission['if-send']) && !empty($submission['if-send'])) return $use_this_form; // or true, i guess

    return $use_this_form; // or `false`, depending on your desired default
}

If you want to check after the fields have been mapped, you can "reuse" the hook '...service_filter_args' and return false to skip, rather than bypass:

add_filter('Forms3rdPartyIntegration_service_filter_args', 'f3i_conditional_post', 10, 3);
function f3i_conditional_post($post_args, $service, $form) {
    // your skip scenarios, checking `body` subarray instead
    if(isset($post_args['body']['maybe-send']) && ...) return false;

    // regular behavior
    return $post_args;
}

How do I resend a service call?

Using public instance functions send and handle_results:

$f3p = Forms3rdPartyIntegration::$instance;
$debug = $f3p->get_settings();
// $sid - maybe get it from the current filter
// $form - maybe get it from the current filter
// $submission - probably save it somewhere, or rebuilt it from a database entry, etc
// $service = $f3p->get_services()[$sid];

$sendResult = $f3p->send($submission, $form, $service, $sid, $debug);
if($sendResult === Forms3rdPartyIntegration::RET_SEND_STOP || $sendResult === Forms3rdPartyIntegration::RET_SEND_SKIP) return;

$response = $sendResult['response'];
$post_args = $sendResult['post_args'];

return $f3p->handle_results($submission, $response, $post_args, $form, $service, $sid, $debug);

How do I include part of the response in another service call?

See "Forms: 3rdparty Post Again"

How do I include part of the response the contact form results?

See "Forms: 3rdparty Inject Results"

However, currently only confirmed working with Gravity Forms.

Screenshots

Please note these screenshots are from the previous plugin incarnation, but are still essentially valid.

  1. Admin page - create multiple services, set up debugging/notice emails, example code Admin page - create multiple services, set up debugging/notice emails, example code

  2. Sample service - mailchimp integration, with static and mapped values Sample service - mailchimp integration, with static and mapped values

  3. Sample service - salesforce integration, with static and mapped values Sample service - salesforce integration, with static and mapped values

Changelog

1.8

1.7.9

1.7.8

1.7.7

1.7.6

1.7.5

1.7.4

1.7.3

1.7.2.1

1.7.2

1.7

1.6.6.5

1.6.6.4

1.6.6.3

1.6.6.1

1.6.6

1.6.5.1

1.6.4.3

1.6.4.2

1.6.4.1

1.6.4

1.6.3.1

1.6.3

1.6.1

Due to the new common form extension base, the way forms are identified in the settings has been changed. Deactivating and reactivating the plugin (which happens automatically on upgrade, but not FTP or other direct file changes) should correct your existing settings.

Depending on how many services you have configured, the upgrade path may DESELECT your form selections in each service or otherwise break some configurations. If you are concerned this may affect you, please export the settings so you can reapply your selections.

1.4.9

Updated cf7 plugin to match their latest changes.

1.4.8.1

Trying to add some clarity to the admin pages

1.4.8

1.4.7

1.4.6

1.4.5

1.4.4

1.4.3

1.4.2

1.4.1

1.4.0

1.3.2

1.3.1

1.3.0

moved "external" includes (hidden-field plugin) to later hook to avoid conflicts when plugin already called

1.2.3

changed filter callback to operate on entire post set, changed name

1.2.2

fixed weird looping problem; removed some debugging code; added default service to test file

1.2

moved filter to include dynamic and static values; icons

1.1

added configuration options, multiple services

1.0

base version, just directly submits values

Upgrade Notice

1.8

Now that Ninja Forms works again with this plugin there may be conflicts with the related sub-plugin "Forms 3rdparty File Attachments". Please deactivate the "File Attachments" plugin if you are unable to submit your contact form.

1.6.1

Due to the new common form extension base, the way forms are identified in the settings has been changed. Deactivating and reactivating the plugin (which happens automatically on upgrade, but not FTP or other direct file changes) should correct your existing settings. See Changelog for more details.

1.4.6

1.4.5

You may need to configure the 'failure message', or at least refresh and save the admin settings, to avoid PHP 'empty index' warnings.

1.4.0

Accommodates Gravity Forms. Complete plugin rewrite, namespace since 1.3.2 incarnation as CF7 3rdparty Integration. Incompatible with previous versions.

1.3.1

See 1.3.0 notice

1.3.0

Fixes should accomodate CF7 < v1.2 and changes to >= v1.2 -- please test and check when upgrading, and report any errors to the plugin forum.

Hooks

Please note that this documentation is in flux, and may not be accurate for latest rewrite 1.4.0

  1. add_action('Forms3rdPartyIntegration_service_a#', $response, $param_ref);
    • hook for each service, indicated by the # - this is given in the 'Hooks' section of each service
    • provide a function which takes $response, &$results as arguments
    • allows you to perform further processing on the service response, and directly alter the processing results, provided as array('success'=>false, 'errors'=>false, 'attach'=>'', 'message' => '');
      • success = true or false - change whether the service request is treated as "correct" or not
      • errors = an array of error messages to return to the form
      • attach = text to attach to the end of the email body
      • message = the message notification shown (from CF7 ajax response) below the form
    • note that the basic "success condition" may be augmented here by post processing
  2. add_action('Forms3rdPartyIntegration_service', $response, $param_ref, $sid);
    • same as previous hook, but not tied to a specific service
  3. add_filter('Forms3rdPartyIntegration_service_filter_post_#, ...
    • hook for each service, indicated by the # - this is given in the 'Hooks' section of each service
    • allows you to programmatically alter the request parameters sent to the service
    • should return updated $post array
  4. add_filter('Forms3rdPartyIntegration_service_filter_post', 'YOUR_HOOK', 10, 4);
    • in addition to service-specific with suffix _a#; accepts params $post, $service, $form, $sid
  5. add_filter('Forms3rdPartyIntegration_service_filter_args', 'YOUR_HOOK', 10, 3);
    • alter the args array sent to wp_remote_post
    • allows you to add headers or override the existing settings (timeout, body)
    • if you return an array containing the key response_bypass, it will skip the normal POST and instead use that value as the 3rdparty response; note that it must match the format of a regular wp_remote_post response.
    • Note: if using response_bypass you should consider including the original arguments in the callback result for debugging purposes.

  6. add_action('Forms3rdPartyIntegration_remote_failure', 'mycf7_fail', 10, 5);

    • hook to modify the Form (CF7 or GF) object if service failure of any kind occurs -- use like:

      function mycf7_fail(&$cf7, $debug, $service, $post, $response) { $cf7->skip_mail = true; // stop email from being sent // hijack message to notify user ///TODO: how to modify the "mail_sent" variable so the message isn't green? on_sent_ok hack? $cf7->messages['mail_sent_ok'] = 'Could not complete mail request:** ' . $response['safe_message']; }

    • needs some way to alter the mail_sent return variable in CF7 to better indicate an error - no way currently to access it directly.

  7. add_action('Forms3rdPartyIntegration_service_settings', 'YOUR_HOOK', 10, 3)
    • accepts params $eid, $P, $entity corresponding to the index of each service entity and this plugin's namespace, and the $entity settings array
    • allows you to add a section to each service admin settings
    • name form fields with plugin namespace to automatically save: $P[$eid][YOUR_CUSTOM_FIELD] $rarr; Forms3rdPartyIntegration[0][YOUR_CUSTOM_FIELD]
  8. add_action('Forms3rdPartyIntegration_service_metabox', 'YOUR_HOOK', 10, 2)
    • accepts params $P, $entity corresponding to the index of each service entity and this plugin's namespace, and the $options settings array (representing the full plugin settings)
    • allows you to append a metabox (or anything else) to the plugin admin settings page
    • name form fields with plugin namespace to automatically save: $P[YOUR_CUSTOM_FIELD] $rarr; Forms3rdPartyIntegration[YOUR_CUSTOM_FIELD]
  9. add_filter('Forms3rdPartyIntegration_debug_message', 'YOUR_HOOK', 10, 5);
    • bypass/alternate debug logging
  10. add_filter('Forms3rdPartyIntegration_plugin_hooks', 'YOUR_HOOK', 10, 1);
    • Accepts an array of contact form plugin hooks to attach F3p to, and returns that array. Modify result to attach to additional plugin hooks, like GF edit.
  11. add_filter('Forms3rdPartyIntegration_service_filter_url', 'YOUR_HOOK', 10, 2);
    • hook a function that takes the $service_url, $post_args and returns the endpoint $url
    • used to modify the submission url based on mappings or other information
    • $post_args contains the body and other wp_remote_post details

Basic examples provided for service hooks directly on plugin Admin page (collapsed box "Examples of callback hooks"). Code samples for common CRMS included in the /3rd-parties plugin folder.

Stephen P. Kane Consulting

From the website and Handpicked Tomatoes:

Transparent and Holistic Approach

Transparency is good. It's amazing how many web design sites hide who they are. There are lots of reasons, none of which are good for the customer. We don't do that. I'm Stephen Kane, principal web craftsman at HandpickedTomatoes, and I'm an Orange County based freelancer who occasionally works with other local freelancers and agencies to deliver quality web solutions at very affordable prices. We work to earn the right to be a trusted partner. One that you can turn to for professional help in strategizing, developing, executing, and maintaining your Internet presence. We take a holistic view. Even if a project is small, our work should integrate into the big picture. We craft web architecture and designs that become winning websites that are easy to use and to share. We custom build social network footprints on sites like linkedin, facebook, twitter, youtube, flickr, yelp!, and google places and integrate them into your website to leverage social marketing. We help you set up and execute email campaigns, with search engine marketing, with photography, with site copy and content and anything else that you need in order to have a successful Internet presence. Through this holistic approach, we work with clients to grow their sales, improve their brand recognition, and manage their online reputation.