Docs/Workflow Playbooks/Integration Manual

Integration workflow manual

If an app connects to BookFlow, this page shows what changes.

Use this manual to explain CRM, HR, TicketPro, Ecommerce, FlowOS, and Custom Apps. Each workflow follows the same chain: connect, run, map, update BookFlow, prove it on screen, then choose the next operator action.

Integration console map

Annotated integrations console — The console is not only a settings page. It is the operations view for connector health, event templates, activity, payload inspection, local record links, and custom app workflows.

Connector health.Shows active, healthy, stale, failed, and webhook-ready connectors so the operator knows what can run.

Provider/custom app sidebar.Each provider has credentials, subscriptions, field mappings, test actions, and status.

Event map.Answers what happens when the outside app sends an event or BookFlow sends one back.

Activity and payload proof.Every test, sync, webhook, simulator run, or local result should be traceable from activity to linked record.

Run Workflow Test

Annotated workflow simulator result — The simulator exists so a vendor can see cause and effect without waiting for a real external app event.

Expected behavior

BookFlow first tries the real signed webhook or test-sync path for the selected connection.
If credentials are incomplete, it replays seeded demo data and marks the result as Demo replay.
The result opens the Activity view with the generated log selected.
The selected workflow shows incoming event, mapped fields, local result, linked record, payload drawer, and operator next action.

If you connect this app

CRM

Leads become operational bookings

Sync imports sales leads into Lead Intake. A vendor converts a lead by choosing service, location, staff, date, and slot. BookFlow creates a normal booking and saves the external mapping.

Staff data affects availability

Branch sync updates locations, employee sync updates staff profiles, and leave sync blocks time that should not be offered to customers.

TicketPro

Support cases stay beside bookings

Customer support requests or AI receptionist follow-up handoffs attach one external ticket reference to a booking or conversation. Paid cancellations can also show manual refund review context.

Ecommerce

Orders become wallet benefits

Paid order events can create or update a customer membership, package credits, voucher benefit, or a note-only event. The result appears in wallet, booking, payment, and Programs usage views.

FlowOS

Reception channels carry context

Inbound conversations become receptionist/customer context. Outbound lifecycle events can tell the external channel about booking created, rescheduled, cancelled, or completed states.

Custom Apps

Tenant-defined but controlled

A tenant can define app key, event key, mappings, and one predefined local action. No arbitrary custom code is executed.

Provider-by-provider workflows

Provider	Connect/setup	Run/use	BookFlow result	Where to prove it	Common confusion
CRM	Store API/base URL, webhook key, secret, and status.	Run sync, run test, or convert lead.	Lead Intake rows, booking after conversion, external lead-to-booking mapping.	Lead Intake, Bookings, Calendar, Activity, Mappings.	Sync imports leads; it does not auto-book every lead.
HR	Store HR credentials and selected sync scope.	Sync branches, employees, and leave.	Locations, staff profiles, availability/time-off inputs.	Locations, Staff, Calendar, Activity.	HR can provide people and leave, but service assignment still matters.
TicketPro	Store support connector, department/category settings, and generated webhook credentials.	Submit support request, create receptionist follow-up case, or cancel paid booking.	Ticket/reference is attached; receptionist conversation becomes TicketPro Handoff and duplicate BookFlow follow-up is blocked.	Customer Portal, Booking detail, Receptionist, Activity.	BookFlow does not send the customer reply from receptionist follow-up; the reply belongs in TicketPro.
Ecommerce	Store ecommerce credentials and entitlement event rules.	Receive paid order event or simulator replay.	Membership, package, voucher, or note-only entitlement result.	Customer wallet, Programs, Booking benefit summary, Payment ledger, Activity.	A paid order must map to a known customer/email and benefit type.
FlowOS	Store outbound webhook URL and channel settings.	Receive conversation or send booking lifecycle event.	Receptionist conversation context or outbound lifecycle log.	Receptionist, customer/conversation context, Activity.	FlowOS is not the booking engine; it carries channel context and lifecycle messages.
Custom App	Create app key, event key, secret, mapping rules, local action.	Receive signed webhook or run simulator.	Lead, conversation, entitlement, ticket reference, or note-only activity.	Activity selected workflow, payload drawer, linked local record, mappings.	Custom app v1 only runs predefined actions, not arbitrary code.

CRM integration path

CRM is the sales and marketing system; BookFlow is the booking proof system.

Connect CRM with base URL, API token, webhook key, connector slug, and active status.
Run Test to prove credentials and schema/status support; run Sync to pull leads into Lead Intake.
Convert only the lead the vendor chooses. Conversion requires location, service, staff/date/slot, and creates a normal BookFlow booking.
BookFlow stores an external mapping so support can trace the CRM lead to the local booking and avoid duplicate conversion.
When Programs launches a paid ad draft, BookFlow sends the draft payload to CRM and stores CRM campaign/draft IDs plus the CRM cockpit URL. CRM remains responsible for ad accounts, provider credentials, approval, activation, publishing, and audit.

CRM action	BookFlow record created or updated	Visible proof	What BookFlow does not do
Lead sync	Integration lead and sync log.	Lead Intake, Activity selected payload, CRM Funnel metric.	It does not auto-book every lead.
Lead conversion	Booking, customer profile, external lead-to-booking mapping.	Bookings, Calendar, Lead Intake converted status, Activity.	It does not overwrite CRM ownership of the lead.
Booking usage event	Outbound sync log and CRM usage payload.	Activity row with push direction and `/api/crm/v1/usage-events` endpoint.	It does not require CRM to be the booking engine.
Paid ad draft from Programs	Paid ads retention campaign, external CRM ad draft mapping, sync log.	Programs Activity, CRM campaign/draft IDs, CRM ads cockpit link.	It does not publish, activate, or edit Meta/Facebook or Google accounts directly.

TicketPro receptionist workflow

Step	TicketPro configured	TicketPro not configured	Proof
AI flags follow-up	Conversation stays Open with human follow-up priority.	Same Open conversation and priority flag.	Receptionist detail shows status, confidence, and transcript.
Staff handles it	Click Create TicketPro Follow-up Case and submit subject/context.	Click Resolve Locally and submit one internal note.	Confirmation explains no BookFlow customer message is sent.
System result	BookFlow creates requester ticket, stores external mapping, and marks conversation TicketPro Handoff.	BookFlow stores local resolution metadata and marks conversation Resolved.	Ticket number/status/priority or local note appears on detail.
Duplicate protection	Further TicketPro or local follow-up is blocked.	Further local follow-up is blocked until Reopen Conversation.	Button disappears and handled-state copy is visible.

Custom apps

App name and app key.The app key separates multiple custom apps owned by the same tenant.

First event.The event key tells BookFlow which template and mapping rules apply.

Local action.The safe action can create a lead, conversation, entitlement, ticket reference, or note-only event.

Field mapping.Remote payload values become local fields such as customer email, booking id, plan key, ticket id, or remote id.

Workflow test.The test should create a log and show the mapped result before a real external app sends traffic.

Payload and mapping proof

Payload drawer

What the app sent

Shows request payload, response/local result, provider, event key, direction, correlation id, and replay or real-path mode.

Mapped fields

How BookFlow read it

Shows remote field to local field mappings, required fields, transform type, missing values, and local action selected.

Linked local record

What changed

Links to lead intake, booking, customer wallet entitlement, conversation, support case, or note-only activity depending on provider.

Operator action

What to do next

Convert lead, fix mapping, open customer wallet, review refund, attach ticket, verify staff leave, or inspect the external mapping.

Technical reference: integration records and fields

Operational logs should carry provider/custom app key, event key, direction, correlation id, local result reference, short summary, timeline metadata, request payload, response/local result, and replay mode when seeded data is used.

Field mappings should show remote field, local field, required flag, transform type, and failure reason when a required field is missing.

Troubleshooting

User says	Check first	Likely explanation
CRM is connected but no bookings appeared.	Lead Intake and Activity.	CRM sync imports leads. Bookings appear only after a vendor converts a lead.
HR is connected but slots look wrong.	Staff, Locations, leave/time-off, Activity.	Imported staff may not be assigned to services or leave may not be mapped.
TicketPro case is missing.	Support request, booking metadata, Activity.	TicketPro may be inactive or the support request did not create/link a ticket.
Ecommerce order did not show in wallet.	Payload drawer and external mapping.	The order may not map to a known customer or benefit entitlement.
Run Workflow Test says Demo replay.	Credentials, webhook secret, connector status.	The real path was incomplete, so seeded data was replayed intentionally.