Contact Export Profile

The Contact Export Profile synchronizes customer data from Magento to FreeAgent, creating and updating contacts in your accounting system. This profile ensures customer information is consistent across both platforms.

Overview

Profile Type ID: freeagent_contact_export Direction: Magento → FreeAgent Purpose: Export Magento customer accounts as FreeAgent contacts

What Gets Exported

• Customer Accounts: Complete customer information as FreeAgent contacts
• Customer Addresses: Billing and shipping addresses
• Company Information: Company name, tax IDs, business details
• Contact Details: Email, phone, name information
• Customer Metadata: Additional customer attributes

Primary Use Cases

• Order Processing: Export customers to FreeAgent before or during invoice export
• CRM Integration: Synchronize customer data for accounting and reporting
• Guest Checkout: Automatically create FreeAgent contacts for guest orders
• B2B Management: Export business customers with company accounts

Export Workflow

Magento Customers
       ↓
[Customer Collection]
       ↓
[Contact Resolution]
       ↓
[Contact Data Generation]
       ↓
[API Export to FreeAgent]
       ↓
[Status Update & Logging]

Configuration Reference

All configuration options are found at: Admin Panel > Byte8 > FreeAgent > Profiles > [Your Contact Export Profile]

1. Client Configuration

Client

Field: client_id Type: Select (Required) Scope: Global

Select the FreeAgent client configuration to use for this profile. The client contains the OAuth credentials and connection settings required to communicate with your FreeAgent system.

Actions:

• Edit - Modify existing client configuration
• New Client - Create a new FreeAgent client connection
• Collect Configuration Data - Fetch contact categories and options from FreeAgent
• Delete Configuration Data - Remove cached configuration data

Initial Setup

After selecting a client, click Collect Configuration Data to populate dropdown options throughout the profile configuration.

---

2. Schedule Configuration

Enable Schedule

Field: status Type: Checkbox Default: Enabled Scope: Global

Enable automatic contact export processing via the scheduler.

When to Enable:

• Production environments with regular customer registrations
• Automated contact sync workflow
• Pre-requisite for invoice export (contacts must exist first)

When to Disable:

• Manual contact review before export
• Testing and configuration phases

Schedule

Field: schedule_id Type: Select (Required when enabled) Scope: Global

Select the cron schedule that determines when this contact export profile runs automatically.

Common Schedules:

• Every 15 minutes - Near real-time contact sync (recommended)
• Every 30 minutes - Standard contact sync
• Every 60 minutes - Low-volume stores
• Custom - Define your own cron expression

Process Batch Size

Field: process_batch_size Type: Number Default: 100 Scope: Global

Number of contacts to process in each batch during scheduled execution.

Recommendations:

• Small stores (< 1,000 customers): 100-200
• Medium stores (1,000-10,000 customers): 100-150
• Large stores (> 10,000 customers): 50-100

Performance Impact

Higher batch sizes consume more memory. Monitor your PHP memory_limit (recommended: 2GB+) when processing large batches.

Enable Automatic Retry on Failure

Field: enable_retry_on_failure Type: Checkbox Default: Disabled Scope: Global

Automatically retry failed contact exports on subsequent schedule runs.

How It Works:

1. Contact export fails (API timeout, connection error)
2. Contact marked for retry with attempt counter
3. System retries on next scheduled run
4. After max attempts exceeded, requires manual intervention

Maximum Retry Attempts

Field: retry_max_attempts Type: Number Default: 3 Scope: Global

Maximum number of retry attempts before marking a contact as permanently failed.

---

3. HTTP API Configuration

Configure how the profile interacts with the FreeAgent API.

API Behavior

Controls how contacts are created and updated in FreeAgent:

• Create New: Only create contacts that don't exist in FreeAgent
• Update Existing: Only update contacts that already exist
• Create and Update: Create new contacts and update existing ones (recommended)

---

Processing Pipeline

The Contact Export service uses a multi-stage processor pipeline:

Generators

Generator	Sort Order	Purpose
Contact Data	10	Generate contact payload from Magento customer data

Processors

Processor	Sort Order	Purpose
Contact Creation	40	Create or update contact in FreeAgent via API

Post-Processors

Post-Processor	Sort Order	Purpose
Queue & Log	100	Update queue status and log processing results

Entity Data

Contact sync data is tracked in the freeagent_contact_entity table:

Column	Type	Description
entity_id	INT	Primary key
customer_id	INT	Magento customer ID
email	VARCHAR	Contact email address
status	VARCHAR	Sync status
queue_status	VARCHAR	Queue processing status
message	TEXT	Sync messages (JSON)
metadata	TEXT	Additional data (JSON)
collected_at	DATETIME	When data was collected from FreeAgent
processed_at	DATETIME	When data was last processed

CLI Commands

# Collect contacts from FreeAgent
bin/magento fa_contact:collect

# Export all pending contacts to FreeAgent
bin/magento fa_contact:export

# Export specific contacts by profile ID
bin/magento fa_contact:export --profile=1

# Export specific contacts by entity ID
bin/magento fa_contact:export --id=42

# Dry run (preview without sending)
bin/magento fa_contact:export --dry-run

# Import contacts from FreeAgent
bin/magento fa_contact:import

Best Practices

1. Export contacts before invoices - FreeAgent requires a contact to exist before creating an invoice for them. Schedule contact export to run before invoice export.
2. Use sandbox for testing - Test contact export with sandbox mode to avoid creating test contacts in your live FreeAgent account.
3. Monitor the entity table - Check freeagent_contact_entity for failed exports and investigate error messages.
4. Set appropriate batch sizes - Start with the default (100) and adjust based on execution time and memory usage.

Troubleshooting

Contacts Not Exporting

Problem: Scheduled contact export runs but no contacts are exported

Solutions:

1. Verify the profile schedule is enabled
2. Check that customers exist in the queue
3. Review var/log/freeagent/contact.log for errors
4. Verify FreeAgent API credentials are valid
5. Test with CLI: bin/magento fa_contact:export --dry-run

Duplicate Contacts in FreeAgent

Problem: Same customer appears multiple times in FreeAgent

Solutions:

1. Check the contact resolution logic configuration
2. Verify the freeagent_contact_entity table for duplicate mappings
3. Review the API behavior setting (create vs. update)

API Rate Limiting

Problem: Export fails with rate limit errors

Solutions:

1. Reduce batch size
2. Increase schedule interval
3. Check var/log/freeagent/contact.log for throttling messages
4. Increase connection retry attempts

Next Steps

1. Invoice Export - Configure invoice synchronization
2. Credit Memo Export - Configure credit memo sync
3. CLI Commands - Full CLI reference

Related Documentation

• About Profiles
• Client Configuration
• Profile Configuration