This document explains how LaunchSMS connects to FieldPulse, how data flows through the integration, and how the form builder sends submissions to FieldPulse.

Setup & Configuration

1. Enable the integration – The FieldPulse integration card on /company/integrations becomes actionable when the company has Integrations/API Access.
2. Enter API credentials – The detail page (/company/integrations/fieldpulse, FieldPulseController@saveFieldPulseSettings) requires:

• FieldPulse API Key (You will also need to contact FieldPulse at support@fieldpulse.com or use the chat feature in the bottom right corner of your screen when you are logged into your FieldPulse dashboard).
• Optional defaults: Job Type, Status (1–6), Billing Code (1–10), Send Referral Details flag.
  • Job Status:
    • New (This is typically the status you will use)
    • In Progress
    • Completed
    • Canceled
    • On the way
  • Billing Code: FieldPulse requires a numerical value here (you can leave it on 1)
  • Include referral / UTM details in Job Notes: If you want to include lead attribution data in your web form submissions you will toggle this on.

1. Connectivity Check – After save, FieldPulseService::testConnection() calls GET /version using the stored key. Success toggles is_connected.
2. Webhook URL – Each integration gets a 36‑char webhook_key (generated in FieldPulseIntegration::boot). Your FieldPulse account should post job status updates to https://go.launchsms.com/fieldpulse/webhook/{webhook_key}.

Recent Webhook Events

Captures every webhook call with the integration id, event name, job id, status, raw payload, and timestamps. Indexed for quick filtering in the UI.

Troubleshooting Checklist

1. Check connection – ensure the FieldPulse card says “Connected.” If not, re-save the API key and confirm the /version call works.
2. Verify mappings – on the form edit screen, confirm the FieldPulse dropdowns are populated and the required keys appear in the “Mapped Fields” debug logs.
3. Review payload – use the Laravel log snippet to confirm customer_id, job_type, timestamps, and arrival windows look correct before contacting FieldPulse support.
4. Inspect webhooks – open the integration detail page to see if FieldPulse is calling back with job updates.

---

Form Builder Integration with FieldPulse

This section focuses on how FieldPulse is wired into the LaunchSMS form builder.

Enabling FieldPulse on a Form

1. Navigate to Forms & Data → Form Builder and open/create a form.
2. In the Integration Settings accordion, toggle “Send submissions to FieldPulse”. The toggle persists even if the FieldPulse integration is temporarily disconnected.
3. When the company is connected to FieldPulse, the field editor shows a “FieldPulse Key” dropdown alongside other integrations (ServiceTitan, Jobber, etc.). Without a connection the dropdown stays hidden to avoid invalid mappings.
4. Saving the form runs the required-key validation described above. Missing Customer First/Last Name, Customer Phone, or Job Type mappings block the save with a descriptive error.

Mapping Fields

All FieldPulse-specific targets live inside integrationFieldKeys.fieldpulse_key (see resources/views/FormBuilder/{create,edit}.blade.php). Available targets include:

• Contact data: Customer First/Last Name, Customer Display Name, Customer Email, Customer Phone, Street Address, City, State, Zip/Postal Code.
• Job metadata: Job Type, Job Notes, Field Notes, Status (1–6), Custom Status ID, Status Workflow ID, Billing Code, Job Subtitle, Location Title, Customer Contact ID, Asset IDs, Tags, Generate Invoice.
• Scheduling: Start Time, End Time, Due Date, Customer Arrival Window (Start Time), Customer Arrival Window (End Time).

Tips:

• Map both the preferred date (usually a Date field mapped to Start Time) and the window selector (Radio/Select mapped to Customer Arrival Window (Start Time)) for best UX.
• To create multi-account templates, leave optional keys unmapped; the payload builder automatically excludes nulls.

FieldPulse Form Template

FormBuilderController::getTemplate('fieldpulse') seeds a ready-to-use template featuring:

• Service details (job type, description, field notes).
• Contact info (first/last name, phone, email).
• Service location (address, city, state, zip).
• Scheduling (preferred date, time window, user agreement).

Each template field already carries a fieldpulse_key, ensuring exported forms comply with the required mappings.

Submission Flow

1. Form runtime collects values and posts them to /embed-form-submit.
2. FormEmbedController checks send_to_fieldpulse before doing any extra work.
3. If enabled, it:

• Loads the integration (FieldPulseIntegration).
• Runs mapIntegrationFields() to combine the stored fieldpulse_key metadata with the submission payload.
• Builds the customer/job payload and dispatches FieldPulseService::createCustomerAndJob().

1. Responses (success or error) are attached to fieldpulse_response in the JSON response and logged for operators.

Edge Cases & Enhancements

• Arrival Window Logic – If a user types “Call me to schedule”, the resolver skips sending timestamps so FieldPulse doesn’t display misleading windows.
• Timestamp Normalization – ensureUnixTimestamp() converts ISO strings, plain dates (YYYY-MM-DD), and 10-digit Unix timestamps to the required 10-digit format that FieldPulse expects.
• Referral Metadata – When enabled, the submission’s UTM/source data is appended to the job notes under a “Referral Details” block for downstream reporting.
• Duplicate Customers – All dedupe behavior lives in FieldPulseService so the form layer doesn’t have to request FieldPulse before every submission.

QA / Manual Testing Workflow

1. Create/clone a form using the FieldPulse template.
2. Map any additional custom fields and enable the toggle.
3. Use the provided Postman collection (see fieldpulse_api.json) or curl to verify the API key outside of LaunchSMS if needed.
4. Submit the form using the public preview link. Watch the Laravel logs for:

• Mapping lines (:link:) showing each field pair.
• The payload block under :outbox_tray: and the FieldPulse response under :white_check_mark:.

1. Log in to FieldPulse and confirm the job appears with the correct customer, address, notes, tags, and arrival window.
2. Optionally post a webhook payload to https://go.launchsms.com/fieldpulse/webhook/{webhook_key} to ensure webhook logs update on the integration detail page.

With these steps, developers and support engineers can reason about the FieldPulse integration end-to-end, extend it (e.g., adding new field mappings), or troubleshoot customer issues quickly.