Forms: 3rd-Party Integration

FAQ

I need help / My form isn’t working

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

• the current plugin configuration, including field mappings
• the user submission (as provided by CF7/GF/Ninja)
• the post as sent to the service (applied mapping)
• the response sent back from the service, which hopefully includes error codes or explanations (often is the raw HTML of a success/failure page)

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…

• By default, if more than one value appears in the post request for the same field/key, they will be joined by the ‘separator’ value like &post-values=a,b,c.
• However, if you use [] as the separator it will instead create multiple keys like &post-values[]=a&post-values[]=b&....
• Use [#] to retain the numerical index: &post-values[0]=a&post-values[1]=b&...
• Use [%] to place the numerical index at desired location; specifically useful with nested fields via Xpost below (and issues #11 and #7).

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 https://wordpress.org/support/topic/method-get?replies=2#post-5996489

See ‘Hooks’ section, #5 of https://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. (see “Hooks” section)

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 https://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: https://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: https://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: https://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”

• Github https://github.com/zaus/forms-3rdparty-postagain
• WordPress https://wordpress.org/plugins/forms-3rdparty-post-again/

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

See “Forms: 3rdparty Inject Results”

• Github https://github.com/zaus/forms-3rdparty-inject-results
• WordPress https://wordpress.org/plugins/forms-3rdparty-inject-results/

However, currently only confirmed working with Gravity Forms.