# AAL Connector For LACRM

WordPress plugin that integrates **Contact Form 7** and **Gravity Forms** with **Less Annoying CRM (LACRM)** using their official API v2.

## Requirements

- WordPress 6+
- PHP 8+
- Contact Form 7 and/or Gravity Forms (latest)
- LACRM API key (from [LACRM → Settings → Programmer API](https://account.lessannoyingcrm.com/app/Settings/Api))

## Installation

1. Upload the plugin folder to `/wp-content/plugins/`.
2. Activate **AAL Connector For LACRM** in the WordPress admin.
3. Go to **Settings → AAL Connector For LACRM** and enter your LACRM API key and optional default contact owner.
4. Enable logging if you want to debug syncs.

---

## LACRM APIs Used

This plugin uses **only** these documented LACRM API v2 endpoints:

| API | Purpose |
|-----|---------|
| **GetContacts** | Find existing contact by email (AdvancedFilters: Email IsExactly) to avoid duplicates. Also used to find an existing company by name (RecordTypeFilter: Companies). |
| **CreateContact** | Create a new contact when no match by email. Also used to create a new Company record (IsCompany: true). |
| **EditContact** | Update an existing contact when found by email. |
| **CreateNote** | Add a note to a contact (e.g. form "Notes" field or resubmission history). |
| **GetUsers** | List users for the "Default contact owner" and per-form owner dropdowns. |
| **AssociateContacts** | Link a person contact to a Company contact record. |
| **GetPipelines** | Fetch all pipelines and their statuses for the pipeline dropdown in form settings. |
| **CreatePipelineItem** | Add a contact to a pipeline at a chosen status after form submission. |

- Base URL: `https://api.lessannoyingcrm.com/v2/`
- Auth: POST with `Authorization: YOUR_API_KEY` header and JSON body `{"Function":"...","Parameters":{...}}`

---

## Contact Form 7

### Basic Contact Sync

1. Edit a CF7 form.
2. Open the **Less Annoying CRM** tab.
3. Check **Sync this form to Less Annoying CRM**.
4. Optionally set a contact owner and map form fields to LACRM fields (First Name, Last Name, Email, Phone, Company, Notes).
5. Save. Submissions (after mail is sent) will create or update contacts in LACRM by email.

**Hook used:** `wpcf7_mail_sent`

### Company Creation (optional)

In the **Company Settings** section of the Less Annoying CRM tab:

- Check **Create or link a Company record in LACRM when the Company field above is filled**.
- On submission, if the Company field has a value:
  1. LACRM is searched for a company with that exact name.
  2. If found — the existing company is linked to the contact.
  3. If not found — a new Company record is created and linked.

> The Company field must be mapped in the field mapping table above for this to work.

### Pipeline (optional)

In the **Pipeline Settings** section of the Less Annoying CRM tab:

- Check **Add contact to a Pipeline in LACRM after form submission**.
- Select a **Pipeline** from the dropdown (populated from your LACRM account).
- Select a **Status** — the dropdown filters automatically when you pick a pipeline.
- Choose **When to add**:
  - *Only for new contacts* — pipeline item is created only on the first submission (new contact).
  - *Every submission* — pipeline item is created for both new and returning contacts.
- Optionally map a **Pipeline note** form field to include a note on the pipeline item.

---

## Gravity Forms

### Basic Contact Sync

1. Edit a form → **Settings → Less Annoying CRM** (feed add-on).
2. Add a feed, enable **Sync this form to Less Annoying CRM**, and map fields (First Name, Last Name, Email, Phone, Company, Notes).
3. Optionally set a contact owner for the feed.
4. Save. Submissions will create or update contacts in LACRM by email.

**Hook used:** `gform_after_submission` (via GFFeedAddOn)

### Company Creation (optional)

In the **Company Settings** section of the feed:

- Enable **Create or link a Company record in LACRM when the Company field is filled**.
- Behaviour is identical to CF7: finds an existing company by name or creates a new one, then links it to the contact.

### Pipeline (optional)

In the **Pipeline Settings** section of the feed:

- Enable **Add contact to a Pipeline in LACRM after form submission**.
- Select a **Pipeline** and the initial **Status** (the status dropdown labels each option as "Pipeline: Status" for clarity).
- Choose **When to add** (new contacts only, or every submission).
- Optionally map a form field to use as the **Pipeline note**.

> The Status dropdown cascades automatically based on the selected Pipeline when JavaScript is enabled.

---

## Field Mapping

| Form field | LACRM destination |
|---|---|
| First Name + Last Name | Combined as **Name** (required for CreateContact) |
| Email | Used to match existing contacts; required |
| Phone | Stored on contact |
| Company | Stored as LACRM "Company Name" text field; also used for Company record creation if enabled |
| Notes | Stored in **Background Info**; also added as a **Note** on new contacts |

---

## Sync Logic (both CF7 and GF)

```
Form submitted
    ↓
Find contact by email (GetContacts)
    ├── Found  → EditContact + CreateNote (resubmit history)
    └── Not found → CreateContact + CreateNote (if notes provided)
    ↓
Company enabled + company name filled?
    ├── Find company by name (GetContacts, Companies filter)
    │   ├── Found  → AssociateContacts (link to existing)
    │   └── Not found → CreateContact (IsCompany:true) → AssociateContacts
    ↓
Pipeline enabled + pipeline + status selected?
    ├── Trigger = "new only" + contact was existing → skip
    └── Otherwise → CreatePipelineItem (with optional note)
```

---

## Logging

Enable **Enable logging** under **Settings → AAL Connector For LACRM**. Log entries are stored in WordPress options and can be viewed and cleared on the same settings page. Each sync step (contact created/updated, company linked, pipeline item created) is logged individually.

---

## File Structure

```
aal-connector-for-lacrm/
├── aal-connector-for-lacrm.php          # Main plugin file + LACRM_FIELD_KEYS constant
├── includes/
│   ├── class-lacrm-api.php              # LACRM API v2 client
│   │                                    #   GetContacts, CreateContact, EditContact,
│   │                                    #   CreateNote, GetUsers, GetPipelines,
│   │                                    #   CreatePipelineItem, find_company_by_name,
│   │                                    #   create_company, associate_contacts
│   ├── class-lacrm-logger.php           # Optional debug logging (WP options)
│   ├── class-lacrm-admin-settings.php   # Settings page (API key, default owner, log)
│   ├── class-lacrm-contact-form-7.php   # CF7 editor panel + submission sync
│   │                                    #   Includes: company sync, pipeline sync
│   └── class-lacrm-gravity-forms.php    # GF feed add-on
│                                        #   Includes: company sync, pipeline sync
├── assets/
│   ├── css/
│   │   └── admin-settings.css           # Settings page + CF7/GF editor panel styles
│   └── js/
│       ├── settings.js                  # API key verify (settings page)
│       └── lacrm-editor.js              # CF7 + GF editor: pipeline cascade, show/hide
└── README.md
```

---

## Changelog

### 1.0.1

- Improved Contact Form 7 editor experience with a cleaner LACRM settings UI and tabbed sections.
- Fixed Contact Form 7 asset loading so LACRM editor styles/scripts load reliably on CF7 screens.
- Improved pipeline parsing for Contact Form 7 and Gravity Forms to support additional LACRM response key formats.
- Fixed pipeline status dropdown behavior to show statuses only after selecting a pipeline.
- Updated Gravity Forms LACRM feed settings to require a saved API key before showing full feed configuration.
- Added clearer setup guidance when API key/assignee configuration is incomplete.

### 1.0.0

- Initial release with Contact Form 7 and Gravity Forms sync support.
- Contact create/update flow with duplicate handling by email.
- Company linking/creation support.
- Pipeline support with optional notes.

---

## License

GPL v2 or later.