Profile Setup & Auto-Configuration

Mage2Plenty includes an intelligent setup system that automates much of the initial configuration process. This guide covers both the initial system setup and the profile auto-configuration features.

Overview

The setup process consists of two main phases:

graph LR
    A[Phase 1: Initial Setup] --> B[Phase 2: Profile Auto-Configuration]
    A --> C[Collect Config Data]
    A --> D[Create System Properties]
    B --> E[Detect Missing Config]
    B --> F[Generate Suggestions]
    B --> G[Apply Configuration]

Phase 1: Initial Setup

Before creating profiles, you must run the initial setup to collect configuration data from PlentyONE and create necessary system properties.

Complete Setup (Recommended)

Run the complete setup wizard which handles both collection and creation:

bin/magento plenty:setup:init

This command will:

✅ Collect configuration data from PlentyONE API
✅ Create system properties in PlentyONE
✅ Prepare the system for profile creation

Expected output:

╔══════════════════════════════════════════╗
║     Mage2Plenty Complete Setup Wizard    ║
╚══════════════════════════════════════════╝

Running complete setup for all modules...

══════════════════════════════════════════════
Phase 1: Collecting Configuration Data
══════════════════════════════════════════════

✓ Collecting referrers...
✓ Collecting shipping countries...
✓ Collecting shipping profiles...
✓ Collecting VAT configurations...
✓ Collecting web stores...
✓ Collecting warehouse configurations...

══════════════════════════════════════════════
Phase 2: Creating System Properties
══════════════════════════════════════════════

✓ Creating default referrer (magento)...
✓ Creating media type referrers...
✓ Creating order properties...
✓ Creating customer properties...
✓ Creating item properties...

✓ Complete setup finished successfully!

Next Steps:
1. Navigate to Admin → Plenty Profiles
2. Create profiles for each module (Import/Export)
3. Configure mappings in each profile
4. Test with sample data before full synchronization

Selective Module Setup

If you only need specific modules:

# Setup only order module
bin/magento plenty:setup:init --modules=order

# Setup multiple modules
bin/magento plenty:setup:init --modules=customer,item,order,stock

Dry Run Preview

See what will be created without making changes:

bin/magento plenty:setup:init --dry-run

Individual Phase Commands

Run phases separately if needed:

Step 1: Collect Configuration Data

# Collect all configuration data
bin/magento plenty:setup:collect

# Collect specific types
bin/magento plenty:setup:collect --type=referrer,shipping,vat

# List available collectors
bin/magento plenty:setup:collect --list

What Gets Collected:

Referrers (order sources)
Shipping countries and profiles
VAT configurations
Web stores and locations
Item availabilities, barcodes, units
Customer classes
Warehouse configurations

Step 2: Create System Properties

# Create all system properties
bin/magento plenty:setup:create

# Create specific properties
bin/magento plenty:setup:create --type=referrer,order

# List available property managers
bin/magento plenty:setup:create --list

# Verbose output
bin/magento plenty:setup:create --verbose

What Gets Created in PlentyONE:

Default referrer (magento)
Media type referrers (image, small_image, thumbnail, etc.)
Order properties
Customer properties
Item property groups
Attribute set properties

Domain-Specific Setup Commands

Each module provides its own granular setup commands:

Order Module

# Collect order configuration data
bin/magento plenty:order:setup:collect

# Create order properties
bin/magento plenty:order:setup:property

# Complete order setup
bin/magento plenty:order:setup:init

Item Module

# Collect item configuration data
bin/magento plenty:item:setup:collect

# Create item properties
bin/magento plenty:item:setup:property

# Complete item setup
bin/magento plenty:item:setup:init

Customer Module

# Collect customer configuration
bin/magento plenty:customer:setup:collect

# Create customer properties
bin/magento plenty:customer:setup:property

# Complete customer setup
bin/magento plenty:customer:setup:init

Stock Module

# Collect stock/warehouse configuration
bin/magento plenty:stock:setup:collect

Phase 2: Profile Auto-Configuration

After initial setup, Mage2Plenty can automatically configure profiles when you create them.

How Auto-Configuration Works

Create a new profile in Admin
System detects missing configurations
Modal appears with intelligent suggestions
Review and accept suggestions
System applies configuration automatically

Auto-Configuration Features

1. Client Detection

For single-client systems (most common), the client ID is auto-selected:

✓ Client ID: Automatically detected (12345)

2. Store Mapping

System suggests store-to-locale mappings based on your Magento store configuration:

Suggested Store Mappings:
• Default Store View → PlentyONE Locale: English (ID: 1)
• German Store → PlentyONE Locale: German (ID: 2)
• French Store → PlentyONE Locale: French (ID: 3)

3. Category Mapping

For category profiles, suggests root category mappings:

Root Category Mapping:
• Magento Root (ID: 2) → PlentyONE Category (ID: 1)

4. Attribute Mapping Templates

Provides default attribute mapping templates:

{
  "name": "name",
  "description": "description",
  "short_description": "shortDescription",
  "price": "prices",
  "special_price": "salesPrices"
}

Using Auto-Configuration

Via Admin Panel

Navigate to: SoftCommerce → Plenty Profiles
Click: Add New Profile
Select: Profile Type (e.g., "Item Import")
Click: Save

If profile is unconfigured, a modal will appear:

╔════════════════════════════════════════════╗
║  Profile Auto-Configuration Available      ║
╠════════════════════════════════════════════╣
║                                            ║
║  Missing Configurations Detected:          ║
║  • Client ID                               ║
║  • Store Mapping                           ║
║  • Attribute Mapping                       ║
║                                            ║
║  Would you like to apply suggested         ║
║  configurations?                           ║
║                                            ║
║  [Review Suggestions]  [Apply All]  [Skip] ║
╚════════════════════════════════════════════╝

Review Suggestions

Click Review Suggestions to see detailed configuration suggestions:

Client Configuration:
  ✓ Client ID: 12345 (auto-detected)
  Confidence: High

Store Mapping:
  ✓ Default Store → Locale 1 (English)
  ✓ German Store → Locale 2 (German)
  Confidence: High

Attribute Mapping:
  • Default template provided
  • Can be customized after applying
  Confidence: Medium

Apply Configuration

Click Apply All to accept suggestions. The system will:

Save configuration to database
Clear relevant caches
Mark profile as configured
Redirect to profile edit page for fine-tuning

Shared Configuration Between Profiles

Related profiles (Import/Export pairs) can share common configurations:

Import Profile (plenty_item_import) configures:
  • Client ID
  • Store Mapping

Export Profile (plenty_item_export) can inherit:
  ✓ Client ID (shared)
  ✓ Store Mapping (shared)
  + Additional export-specific settings

Common Shared Configurations:

client_config/client_id
store_config/store_mapping
category_config/root_category_mapping

Manual Profile Configuration

If you prefer manual configuration or need to customize:

1. Create Profile

# Profiles are typically created via Admin UI
# Navigate to: SoftCommerce → Plenty Profiles → Add New

2. Configure Basic Settings

Required fields:

Profile Name: e.g., "Item Import - Main Store"
Type ID: e.g., plenty_item_import
Status: Active
Store: Select applicable store

3. Configure Module-Specific Settings

Client Configuration

Client Configuration Tab:
├─ Client ID: [Auto-detected or select]
└─ Connection: Test connection

Store Configuration

Store Configuration Tab:
├─ Store Mapping:
│  ├─ Default Store → Locale 1
│  ├─ German Store → Locale 2
│  └─ French Store → Locale 3
└─ Web Store: Select PlentyONE web store

Category Configuration (for category profiles)

Category Configuration Tab:
├─ Root Category Mapping:
│  └─ Magento Root → PlentyONE Category
├─ Category Attribute Mapping:
│  ├─ Name → name
│  ├─ Description → description
│  └─ Meta Title → metaTitle
└─ Category Tree Sync: Enable

Item Configuration (for product profiles)

Item Configuration Tab:
├─ Attribute Mapping: [Configure attribute mappings]
├─ Price Configuration: [Configure price types]
├─ Stock Configuration: [Configure stock sources]
└─ Image Configuration: [Configure image roles]

Order Configuration (for order profiles)

Order Configuration Tab:
├─ Status Mapping:
│  ├─ Pending → [PlentyONE Status]
│  ├─ Processing → [PlentyONE Status]
│  └─ Complete → [PlentyONE Status]
├─ Payment Method Mapping
├─ Shipping Method Mapping
└─ Order Referrer: Select referrer

Configuration Storage

Configurations are stored in the softcommerce_profile_config table:

-- View profile configuration
SELECT profile_id, path, value
FROM softcommerce_profile_config
WHERE profile_id = 1;

-- Example output:
-- profile_id | path                                          | value
-- 1          | plenty_item_import/client_config/client_id   | 12345
-- 1          | plenty_item_import/store_config/store_mapping| {"1":"1","2":"2"}

Verifying Setup

Check Initial Setup Status

# Verify system properties exist in PlentyONE
bin/magento plenty:system:check

# Check collected configuration data
mysql> SELECT * FROM plenty_client_config;

Verify Profile Configuration

# Export profile configuration
bin/magento profile:export:config --profile=<profile_id>

# Check configuration completeness
# Admin → Plenty Profiles → [Profile] → Configuration Status

Test Profile Execution

# Test with single entity
bin/magento plenty:item:import --sku=TEST-SKU --profile=1 --verbose

Troubleshooting Setup

Issue: "System properties already exist"

Meaning: Properties were created in a previous setup

Action: This is informational, not an error. Proceed with profile creation.

Issue: "Configuration collector failed"

Common causes:

API connection issues
Insufficient API permissions
PlentyONE system unavailable

Solution:

# Test connection
bin/magento plenty:client:test

# Retry collection with verbose output
bin/magento plenty:setup:collect --verbose

# Check API logs
tail -f var/log/plenty_api_error.log

Causes:

Profile already configured
Browser cache issue
JavaScript error

Solution:

Clear browser cache (Ctrl+Shift+R)
Check browser console for errors
Clear Magento cache: bin/magento cache:flush
Manually configure via profile edit page

Issue: "Property creation failed"

Common errors:

"Property already exists" - Property exists, can be ignored
"Insufficient permissions" - API user lacks property creation rights
"Invalid property data" - Check property configuration

Solution:

# Check existing properties in PlentyONE
# Setup → Item → Properties

# Retry with specific type
bin/magento plenty:setup:create --type=order --verbose

Setup Best Practices

Run Complete Setup First
```
bin/magento plenty:setup:init
```
Don't skip this step!
One Module at a Time If troubleshooting, set up modules individually:
```
bin/magento plenty:setup:init --modules=order
```
Document Custom Configurations If you customize auto-configuration suggestions, document why
Test in Staging Run complete setup in staging environment first

Export Configuration After setup, export configuration for backup:

bin/magento profile:export:config --profile=all > profiles_backup.json

Version Control Keep profile configurations in version control for team collaboration

Advanced Configuration

Extending Auto-Configuration

To add auto-configuration for custom profile types:

1. Create Configuration Detector

// YourModule/Model/AutoConfig/YourProfileConfigurationDetector.php
class YourProfileConfigurationDetector implements ProfileConfigurationDetectorInterface
{
    public function isProfileConfigured(int $profileId): bool
    {
        // Check if required configurations exist
        return $this->hasClientConfig($profileId)
            && $this->hasStoreMapping($profileId)
            && $this->hasCustomMapping($profileId);
    }

    public function getMissingConfigurations(int $profileId): array
    {
        // Return array of missing config paths
    }

    public function getProfileType(): string
    {
        return 'your_custom_type';
    }
}

2. Create Auto-Config Service

// YourModule/Model/AutoConfig/YourProfileAutoConfig.php
class YourProfileAutoConfig
{
    public function generateSuggestions(int $profileId): array
    {
        return [
            'client_id' => $this->detectClientId(),
            'store_mapping' => $this->suggestStoreMapping(),
            'custom_config' => $this->generateCustomConfig()
        ];
    }
}

3. Register in DI

<!-- etc/di.xml -->
<type name="SoftCommerce\PlentyProfile\Model\AutoConfig\ConfigurationDetectorPool">
    <arguments>
        <argument name="detectors" xsi:type="array">
            <item name="your_type" xsi:type="object">YourModule\Model\AutoConfig\YourProfileConfigurationDetector</item>
        </argument>
    </arguments>
</type>

Next Steps

After completing setup and profile configuration:

Test First Sync - Perform initial synchronization test
Configure Scheduling - Automate profile execution
Set Up Monitoring - Track profile performance

Profile Creation - Manual profile creation
CLI Commands - Complete CLI reference
System Requirements - Prerequisites

Important: Always run bin/magento plenty:setup:init before creating your first profile. This ensures all necessary system properties and configurations are in place.

Overview​

Phase 1: Initial Setup​

Complete Setup (Recommended)​

Selective Module Setup​

Dry Run Preview​

Individual Phase Commands​

Step 1: Collect Configuration Data​

Step 2: Create System Properties​

Domain-Specific Setup Commands​

Order Module​

Item Module​

Customer Module​

Stock Module​

Phase 2: Profile Auto-Configuration​

How Auto-Configuration Works​

Auto-Configuration Features​

1. Client Detection​

2. Store Mapping​

3. Category Mapping​

4. Attribute Mapping Templates​

Using Auto-Configuration​

Via Admin Panel​

Review Suggestions​

Apply Configuration​

Shared Configuration Between Profiles​

Manual Profile Configuration​

1. Create Profile​

2. Configure Basic Settings​

3. Configure Module-Specific Settings​

Client Configuration​

Store Configuration​

Category Configuration (for category profiles)​

Item Configuration (for product profiles)​

Order Configuration (for order profiles)​

Configuration Storage​

Verifying Setup​

Check Initial Setup Status​

Verify Profile Configuration​

Test Profile Execution​

Troubleshooting Setup​

Issue: "System properties already exist"​

Issue: "Configuration collector failed"​

Issue: "Auto-configuration modal not appearing"​

Issue: "Property creation failed"​

Setup Best Practices​

Advanced Configuration​

Extending Auto-Configuration​

1. Create Configuration Detector​

2. Create Auto-Config Service​

3. Register in DI​

Next Steps​

Related Documentation​

Overview

Phase 1: Initial Setup

Complete Setup (Recommended)

Selective Module Setup

Dry Run Preview

Individual Phase Commands

Step 1: Collect Configuration Data

Step 2: Create System Properties

Domain-Specific Setup Commands

Order Module

Item Module

Customer Module

Stock Module

Phase 2: Profile Auto-Configuration

How Auto-Configuration Works

Auto-Configuration Features

1. Client Detection

2. Store Mapping

3. Category Mapping

4. Attribute Mapping Templates

Using Auto-Configuration

Via Admin Panel

Review Suggestions

Apply Configuration

Shared Configuration Between Profiles

Manual Profile Configuration

1. Create Profile

2. Configure Basic Settings

3. Configure Module-Specific Settings

Client Configuration

Store Configuration

Category Configuration (for category profiles)

Item Configuration (for product profiles)

Order Configuration (for order profiles)

Configuration Storage

Verifying Setup

Check Initial Setup Status

Verify Profile Configuration

Test Profile Execution

Troubleshooting Setup

Issue: "System properties already exist"

Issue: "Configuration collector failed"

Issue: "Auto-configuration modal not appearing"

Issue: "Property creation failed"

Setup Best Practices

Advanced Configuration

Extending Auto-Configuration

1. Create Configuration Detector

2. Create Auto-Config Service

3. Register in DI

Next Steps

Related Documentation