About Profiles

Profiles are the core mechanism for managing data synchronization between Magento 2 and FreeAgent. They provide a flexible, configurable way to automate bidirectional data exchange with minimal manual effort.

What Are Profiles?

A Profile is a configured synchronization task that defines:

What data to synchronize (contacts, invoices, credit memos)
Which direction to sync (export to FreeAgent, import from FreeAgent, or collect data)
How to process the data (batch size, retry logic, transformations)
When to run (manual execution, scheduled cron, or event-triggered)

Think of profiles as "sync jobs" that handle specific data transfer operations between your Magento store and FreeAgent accounting system.

How Profiles Work

Data Flow

┌─────────────┐         ┌─────────────┐         ┌─────────────┐
│             │ Export  │             │ Import  │             │
│   Magento   │────────>│   Profile   │────────>│  FreeAgent  │
│             │         │             │         │             │
│             │<────────│   (Sync)    │<────────│             │
│             │ Import  │             │ Export  │             │
└─────────────┘         └─────────────┘         └─────────────┘

Three-Phase Workflow

Each entity sync follows a three-phase workflow:

Collect - Fetch data from the FreeAgent API and store locally for processing
Export - Generate payloads from Magento data and send to FreeAgent API
Import - Process collected FreeAgent data and update Magento entities

Execution Flow

Trigger: Profile execution starts (manual, cron, or CLI)
Collect: Retrieve data from source system via API
Generate: Create API payloads with correct format and mappings
Process: Transfer data to destination system
Post-Process: Update local entities, manage queue, log results
History: Record execution details, errors, and metrics

Profile Lifecycle

[Created] → [Configured] → [Active] → [Running] → [Completed]
                ↓                          ↓
            [Disabled]                 [Failed]

Created: Profile exists but not configured
Configured: Settings defined, ready for execution
Active: Enabled and available for scheduled execution
Running: Currently processing data
Completed: Execution finished successfully
Disabled: Temporarily deactivated
Failed: Execution encountered fatal error

Profile Types

Magento FreeAgent Integration includes the following profile types:

Contact Profiles

Profile Type	Direction	Purpose
Contact Export	Magento → FreeAgent	Export Magento customers as FreeAgent contacts
Contact Import	FreeAgent → Magento	Import FreeAgent contacts to Magento
Contact Collect	FreeAgent → Local	Fetch contact data from FreeAgent for processing

Use Cases:

Sync customer accounts to FreeAgent contacts
Create contacts for guest checkout customers
Keep address and company details synchronized
Map customer groups to FreeAgent categories

Invoice Profiles

Profile Type	Direction	Purpose
Invoice Export	Magento → FreeAgent	Export Magento orders as FreeAgent invoices
Invoice Import	FreeAgent → Magento	Import invoice status updates from FreeAgent
Invoice Collect	FreeAgent → Local	Fetch invoice data from FreeAgent for processing

Use Cases:

Automatically create invoices in FreeAgent for new orders
Sync invoice status back to Magento
Handle shipping charges and discount line items
Trigger invoice emails from FreeAgent

Credit Memo Profiles

Profile Type	Direction	Purpose
Credit Memo Export	Magento → FreeAgent	Export Magento credit memos as FreeAgent credit notes
Credit Memo Import	FreeAgent → Magento	Import credit memo status from FreeAgent
Credit Memo Collect	FreeAgent → Local	Fetch credit memo data from FreeAgent

Use Cases:

Create credit notes in FreeAgent for Magento refunds
Maintain accurate financial records across platforms
Handle partial refunds and shipping refunds

Profile Architecture

Components

Each profile consists of several key components:

1. Profile Entity

The main profile record stored in byte8_profile_entity:

Profile ID: Unique identifier
Name: Human-readable profile name
Type ID: Profile type identifier (e.g., freeagent_invoice_export)
Status: Current status (enabled/disabled)
Created At / Updated At: Timestamps

2. Configuration

Profile-specific settings stored in byte8_profile_config:

Client Connection: FreeAgent API credentials
Schedule Settings: Cron expression, batch size
Processing Options: Retry logic, queue behavior
Entity Settings: Type-specific configuration

3. Schedule

Automated execution settings stored in byte8_profile_schedule:

Cron Expression: When to run (e.g., */15 * * * * for every 15 minutes)
Status: Schedule active/inactive
Type ID: Associated profile type

4. History

Execution tracking stored in byte8_profile_history:

Status: Success/failure
Type ID: Profile type that was executed
Message: Execution log messages
Created At: Execution timestamp

5. Queue

Entity processing queue stored in byte8_profile_queue:

Subject Entity ID: The entity being processed
Subject Type ID: Entity type identifier
Status: Queue status (pending, processing, success, error)
Metadata: Additional processing data (JSON)

Data Storage

Profiles and entity data are stored in these database tables:

Table	Purpose
`byte8_profile_entity`	Main profile records
`byte8_profile_config`	Profile configuration
`byte8_profile_schedule`	Cron schedule settings
`byte8_profile_history`	Execution history
`byte8_profile_queue`	Async queue messages
`freeagent_contact_entity`	Contact sync tracking
`freeagent_invoice_entity`	Invoice sync tracking
`freeagent_creditmemo_entity`	Credit memo sync tracking

Profile Features

Flexible Scheduling

Manual Execution:

Run on-demand from admin panel
Execute via CLI commands
Trigger from custom code

Cron Scheduling:

Standard cron expressions
Configurable per profile
Independent scheduling for each entity type

Processing Pipeline

Each export service uses a multi-stage processor pipeline:

Generator (sortOrder: 10-30)
    → Processor (sortOrder: 40-50)
        → PostProcessor (sortOrder: 100)

Generators create the API payload data Processors send data to the FreeAgent API PostProcessors handle response data, queue cleanup, and logging

Error Handling

Retry Logic:

Configurable retry attempts per profile
Automatic retry on transient failures
Maximum retry limit to prevent infinite loops

Error Logging:

Detailed error messages in profile history
Per-entity log files for debugging
Email notifications for critical errors

Partial Processing:

Continue processing on item-level failures
Individual entity status tracking
Queue-based recovery for failed items

Performance Optimization

Batch Processing:

Configurable batch sizes per profile
Process multiple records per execution
Memory-efficient chunked operations

Queue Processing:

Asynchronous entity processing
Background workers via Magento message queue
Non-blocking operations

Profile Uniqueness

One Profile Per Type

Profiles are unique by type. You can only have ONE profile of each type in the system.

For example, you cannot create two "Invoice Export" profiles. If you need different scenarios, use:

Filters to control which data is processed
Configuration options to customize behavior
CLI parameters for ad-hoc variations

Profile Management

Admin Interface

Access profiles via: Byte8 > FreeAgent > Profiles

Available Actions:

View: See profile details and status
Edit: Modify configuration
Execute: Run manually
Schedule: Configure cron
Disable: Temporarily deactivate
View History: See execution logs

Command Line Interface (CLI)

Profiles can be managed via CLI:

# Export profile configuration
bin/magento profile:config:export

# Import profile configuration
bin/magento profile:config:import

# Purge profile data
bin/magento profile:data:purge

# Run entity-specific sync
bin/magento fa_contact:export
bin/magento fa_invoice:export
bin/magento fa_creditmemo:export

Best Practices

Profile Configuration

Start Simple: Begin with basic configuration, add complexity gradually
Test Thoroughly: Use sandbox mode and dry-run before enabling production sync
Monitor Execution: Review history and logs regularly
Version Control: Export configurations for backup

Scheduling

Avoid Peak Times: Schedule resource-intensive profiles during off-peak hours
Stagger Executions: Don't run all profiles simultaneously
Monitor Performance: Track execution times and adjust schedules
Set Realistic Intervals: Balance data freshness with system load

Data Integrity

Use Filters: Process only necessary data
Monitor Errors: Review error logs regularly
Test with Sandbox: Always test changes in sandbox first
Backup Before Changes: Export profile config before major changes

Next Steps

Contact Export - Configure contact synchronization
Invoice Export - Set up invoice processing
Credit Memo Export - Configure credit memo sync
CLI Commands - Full CLI reference

What Are Profiles?​

How Profiles Work​

Data Flow​

Three-Phase Workflow​

Execution Flow​

Profile Lifecycle​

Profile Types​

Contact Profiles​

Invoice Profiles​

Credit Memo Profiles​

Profile Architecture​

Components​

1. Profile Entity​

2. Configuration​

3. Schedule​

4. History​

5. Queue​

Data Storage​

Profile Features​

Flexible Scheduling​

Processing Pipeline​

Error Handling​

Performance Optimization​

Profile Uniqueness​

Profile Management​

Admin Interface​

Command Line Interface (CLI)​

Best Practices​

Profile Configuration​

Scheduling​

Data Integrity​

Next Steps​

Related Documentation​

What Are Profiles?

How Profiles Work

Data Flow

Three-Phase Workflow

Execution Flow

Profile Lifecycle

Profile Types

Contact Profiles

Invoice Profiles

Credit Memo Profiles

Profile Architecture

Components

1. Profile Entity

2. Configuration

3. Schedule

4. History

5. Queue

Data Storage

Profile Features

Flexible Scheduling

Processing Pipeline

Error Handling

Performance Optimization

Profile Uniqueness

Profile Management

Admin Interface

Command Line Interface (CLI)

Best Practices

Profile Configuration

Scheduling

Data Integrity

Next Steps

Related Documentation