=== LeadOnForm – Salesforce Integration ===
Contributors: sanplugin
Tags: salesforce, leads, forms, contact-form-7, integration
Requires at least: 6.2
Requires PHP: 7.4
Tested up to: 7.1.3
Stable tag: 1.3.3
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

Connect WordPress forms to Salesforce Leads with HTML forms and optional Contact Form 7 integration.

== Description ==

LeadOnForm connects your WordPress forms to Salesforce Leads. It sends only the form fields selected by the site administrator, using a server-side API connection.

No Salesforce credentials need to be placed in browser-side JavaScript.

**What you can do with LeadOnForm**

* Configure separate Salesforce Sandbox and Production environments.
* Test Salesforce connectivity from the WordPress administration area.
* Send selected fields from generic HTML forms using CSS classes.
* Enable individual Contact Form 7 forms using an explicit opt-in field.
* Create a new Lead or update an existing unconverted Lead when a matching email is found.
* Reduce basic automated spam using a honeypot and IP-based request limiting.
* Review a bounded event log in the WordPress administration area.
* Extend event handling through documented hooks for optional add-ons.

**What you need**

* A WordPress website where you can install and activate plugins.
* A Salesforce organization with API access and permission to create or update Leads.
* Salesforce connection credentials accepted by the plugin.
* A form containing the fields you want to send to Salesforce.

LeadOnForm does not include a Salesforce account or grant Salesforce API permissions automatically. Your Salesforce organization must be configured to accept the fields you submit.

Salesforce is a trademark of Salesforce, Inc. LeadOnForm is an independent project and is not affiliated with or endorsed by Salesforce, Inc.

== Installation ==

1. Download the plugin ZIP from the WordPress Plugin Directory.
2. In WordPress, go to Plugins > Add New Plugin > Upload Plugin.
3. Select the LeadOnForm ZIP file, install it, and activate the plugin.
4. Open LeadOnForm in the WordPress administration area.
5. Configure the connection for your Salesforce Sandbox or Production environment using the credentials required by the plugin.
6. Save your configuration and use the connection test provided by the plugin.
7. Add the required Salesforce field classes to your form, or explicitly enable the Contact Form 7 form you want to integrate.
8. Submit a test form and verify that the expected Lead was created or updated in Salesforce before using the integration with real visitors.

**Important:** Start with Salesforce Sandbox whenever possible. Confirm that the connection and field mapping work correctly before sending real leads to Production.

== Configuration ==

=== 1. Configure Salesforce ===

Open LeadOnForm in the WordPress administration area.

Select the appropriate Salesforce environment and enter the connection credentials required by the plugin. Save the configuration and run the available connection test.

If the connection test fails, check the following:

* The selected environment is correct.
* The credentials correspond to the selected Salesforce organization.
* The Salesforce organization and connected application permit API access.
* The Salesforce user has the required permissions.
* The WordPress server can connect to the Salesforce API.

The exact permissions and authentication requirements depend on your Salesforce configuration.

=== 2. Prepare the Salesforce fields ===

Identify the Lead fields you want to populate. LeadOnForm uses field classes to associate supported form fields with Salesforce field API names.

For example:

* `sf-FirstName`
* `sf-LastName`
* `sf-Company`
* `sf-Email`
* `sf-MobilePhone`

Salesforce requires `LastName` and `Company` for Lead creation. Additional fields must be supported by your Salesforce organization and accessible to the configured user.

=== 3. Send a test submission ===

After configuring the connection and form:

1. Open the page containing your form.
2. Submit test data.
3. Check Salesforce for the expected Lead.
4. Verify that the submitted values were mapped to the correct fields.
5. Review the LeadOnForm event log if the submission fails.

Use test data while validating the integration. Do not assume that a successful WordPress form submission automatically means Salesforce accepted the Lead.

== Generic HTML forms ==

LeadOnForm supports compatible generic HTML forms. Add the `salesforce-lead-form` CSS class to the form and add the appropriate Salesforce field class to each field you want to send.

Example:

    <form class="salesforce-lead-form" method="post">
	    <label>
	        First name
	        <input type="text" name="first_name" class="sf-FirstName">
	    </label>

	    <label>
	        Last name
	        <input type="text" name="last_name" class="sf-LastName" required>
	    </label>

	    <label>
	        Company
	        <input type="text" name="company" class="sf-Company" required>
	    </label>

	    <label>
	        Email
	        <input type="email" name="email" class="sf-Email">
	    </label>

	    <label>
	        Mobile phone
	        <input type="tel" name="mobile" class="sf-MobilePhone">
	    </label>

	    <button type="submit">Send</button>
    </form>

This is a field-mapping example, not a complete implementation of every form-processing requirement. Follow the plugin's supported submission flow and any validation or security requirements for your website.

The form must provide the required Salesforce fields. Additional fields can be included when supported by your Salesforce organization.

== Contact Form 7 ==

Contact Form 7 integration is optional. LeadOnForm does not automatically send every Contact Form 7 submission to Salesforce.

To enable a form:

1. Open the relevant form in Contact Form 7.
2. Add the hidden field `salesforce_lead` with the value `1`.
3. Add the appropriate `sf-` classes to the fields that should be sent to Salesforce.
4. Save the form.
5. Submit a test entry and verify the result in Salesforce.

Example Contact Form 7 markup:

    [hidden salesforce_lead "1"]
    
    [text first_name class:sf-FirstName]
    [text* last_name class:sf-LastName]
    [text* company class:sf-Company]
    [email email class:sf-Email]
    [tel mobile class:sf-MobilePhone]
    
    [submit "Send"]

The example illustrates the opt-in field and field classes. Adjust the form fields to match your actual data requirements and Salesforce configuration.

Only forms explicitly opted in with `salesforce_lead` set to `1` should be sent through the Contact Form 7 integration. Forms without this opt-in are not included by this integration.

== Troubleshooting ==

=== The Salesforce connection test fails ===

Verify the selected environment, credentials, API access, and Salesforce user permissions. Confirm that the credentials belong to the intended Salesforce organization.

=== The form submits, but no Lead appears in Salesforce ===

Check that the form is configured for the appropriate integration. For generic HTML forms, verify the `salesforce-lead-form` class and the `sf-` classes. For Contact Form 7, verify that the hidden `salesforce_lead` field has the value `1`.

Then review the LeadOnForm event log and check whether Salesforce accepted the request.

=== Salesforce rejects the Lead ===

Check that the required `LastName` and `Company` fields are supplied. Also verify Salesforce validation rules, field access, and the permissions of the configured Salesforce user.

=== Some fields are missing or have incorrect values ===

Verify that each field uses the correct Salesforce API name in its `sf-` class. Confirm that the target field exists and can be written by the configured user.

=== Does a successful form submission guarantee a successful Salesforce submission? ===

No. WordPress form processing and Salesforce API processing are separate operations. Verify the result in Salesforce and consult the plugin event log when troubleshooting.

== Extension hooks ==

LeadOnForm provides these hooks for optional extensions:

* `leadonform_submission_completed` — receives one associative array after a successful Lead create/update.
* `leadonform_submission_failed` — receives one associative array after a submission error.

The event payload includes metadata such as `request_id`, `environment`, `status`, `operation`, `http_status`, `salesforce_id` (on success), `error_code` (on failure), `route`, and `occurred_at`.

The payload intentionally excludes form field values, full email addresses, OAuth tokens, and client secrets. Extensions should not assume that an event contains personal data or raw Salesforce error details.

These hooks are intended for add-ons that need to record events or generate reports.

== Privacy ==

The plugin sends form fields selected by the site administrator to the Salesforce instance configured by that administrator.

The plugin stores configuration and a bounded event log in the WordPress database. The log masks email addresses and does not store the complete submitted form payload.

Site administrators are responsible for configuring their Salesforce connection, providing appropriate privacy notices, and complying with applicable laws and their own data-retention policies.

== Frequently Asked Questions ==

= Does this plugin work without Contact Form 7? =

Yes. Compatible generic HTML forms can use the `salesforce-lead-form` class and the appropriate `sf-` field classes.

= Does LeadOnForm send every Contact Form 7 form? =

No. Contact Form 7 forms must explicitly opt in using the `salesforce_lead` hidden field with value `1`.

= Do I need a Salesforce account? =

Yes. You must provide access to a Salesforce organization with API access and the permissions required to create or update Leads.

= Can I test without sending real leads to Production? =

Yes, if your Salesforce organization provides a Sandbox and you configure LeadOnForm to use it. Test the connection and form mapping before switching to Production.

= Why was my Lead rejected? =

Check required fields, Salesforce validation rules, field permissions, and the configured user's access. The event log may help identify the type of submission error.

= Does the plugin include unlimited logs or advanced reports? =

No. The free version retains up to 200 recent events. The extension hooks allow separately distributed add-ons to implement additional event handling, subject to their own functionality and policies.

= Does LeadOnForm include Salesforce credentials or an account? =

No. You must configure your own Salesforce connection and supply the credentials required by the plugin.

== Changelog ==

= 1.3.3 =
* Format the authentication HTTP status in the exception message for static-analysis compatibility.
* Clarified that sanitized redirect status/message query parameters are display-only and do not change state.

= 1.3.2 =
* Normalized HTTP response status codes before use in error handling.
* Added explicit static-analysis annotations for admin request values that are nonce-verified or display-only.
* Updated the Tested up to header to 7.1; validate compatibility on that WordPress version before release.

= 1.3.1 =
* Removed raw Salesforce response bodies from exception messages.
* Improved IP address sanitization for rate limiting.
* Removed development error logging from normal plugin execution.
* Added the required Tested up to readme header.
* Documented nonce handling for the WordPress Settings API sanitizer.

= 1.3.0 =
* Renamed the public-facing plugin to LeadOnForm.
* Added documented success and failure hooks for future extensions.
* Added readme documentation and GPL license metadata.

= 1.2.1 =
* Added honeypot and IP-based rate limiting.
*