Initial Setup Wizard

The Initial Setup Wizard is an interactive, step-by-step tool that guides you through the initial configuration of your Mage2Plenty integration. It automates many manual setup tasks and ensures all required PlentyONE properties are created correctly.

Overview

The wizard streamlines the initial setup process by:

Testing your API connection
Automatically collecting configuration data from PlentyONE
Creating required properties for Magento integration
Validating your setup before completion

Estimated Time: 5-10 minutes

Recommended for First-Time Setup

If you're setting up Mage2Plenty for the first time, we strongly recommend using the Initial Setup Wizard. It reduces configuration errors and ensures all prerequisites are met before you start synchronizing data.

Prerequisites

Before running the wizard, ensure you have:

✅ Installed Mage2Plenty - All modules installed and enabled
✅ Created PlentyONE Admin User - Admin user with English UI language
✅ Collected Credentials - URL, username, password, client ID, owner ID, store ID
✅ Configured Authentication - Entered credentials in SoftCommerce → PlentyONE → Manage Client Connection
✅ Verified Network - Confirmed Magento server can reach PlentyONE API

Configure Authentication First

The wizard requires valid authentication credentials to be configured before running. You can configure credentials via the UI at SoftCommerce → PlentyONE → Manage Client Connection or use the CLI wizard (see Method 3 below). See Client Configuration for credential setup.

Accessing the Wizard

Method 1: Via Configuration Page

Log in to Magento Admin panel
Navigate to Stores → Configuration
Expand Soft Commerce in the left sidebar
Select PlentyONE Integration
In the Authentication Settings section header, click the Actions dropdown button
Select Run Setup Wizard

Method 2: Via Direct URL

Navigate to: System → PlentyONE → Initial Setup

Or access directly: https://your-magento-url.com/admin/plenty_profile/setup/wizard

Method 3: Via CLI Wizards

For command-line configuration (recommended for first-time setup or automation), use the interactive CLI wizards. Setup is split into two steps:

Step 1: Client Connection & API Configuration

# Configure client connection and API settings
bin/magento plenty:client:wizard

# Quick mode - use recommended defaults
bin/magento plenty:client:wizard --quick

What it configures:

Core Settings - Log rotation, email notifications, FontAwesome icons
REST API Settings - Connection timeout, retry logic, debug modes
Client Connection - PlentyONE URL, username, password with connection test

Step 2: Profile System Setup

# Configure profile system and notifications
bin/magento plenty:profile:wizard

# Quick mode - use recommended defaults
bin/magento plenty:profile:wizard --quick

What it configures:

Profile Settings - History retention, cleanup policies
Notification Settings - Log level, retention days, max notifications
Email Alerts - Recipients, thresholds, batch processing settings
Performance Settings - Batch sizes, async processing

Benefits of CLI Wizards:

✅ Interactive prompts - Step-by-step guided configuration
✅ Connection testing - Validates credentials before saving (client wizard)
✅ Token management - Automatically saves and refreshes OAuth tokens (client wizard)
✅ Configuration validation - Validates all input before applying
✅ No browser required - Perfect for SSH access or automated deployments

See CLI Commands Documentation for detailed CLI wizard usage and options.

CLI vs UI Wizard

The CLI wizards (plenty:client:wizard + plenty:profile:wizard) configure system-wide settings and connection credentials, while the UI Initial Setup Wizard (this page) focuses on collecting PlentyONE configuration and creating properties. For first-time setup, run both CLI wizards first, then proceed with the UI wizard.

Wizard Steps

Step 1: Test API Connection

Purpose: Verify that Magento can successfully communicate with your PlentyONE system.

What Happens

The wizard tests the API connection using the credentials configured in your client settings.

Verification Checks:

✓ URL accessibility
✓ SSL certificate validity
✓ Authentication credentials
✓ OAuth token generation
✓ API version compatibility
✓ Network connectivity

Review Connection Settings: The wizard displays your configured PlentyONE URL and client ID
Click "Test Connection": Initiates the connection test
Wait for Results: The test typically completes in 2-5 seconds

Possible Outcomes

✅ Success:

Connection successful!
- Server: https://mystore.plentymarkets-cloud.com
- Client ID: 12345
- API Version: 1.0
- Response Time: 0.85s
- Status: Ready for configuration collection

Proceeding to next step...

The wizard automatically advances to Step 2.

❌ Failure:

Connection failed!
- Error: Invalid credentials
- HTTP Status: 401 Unauthorized
- Message: The provided username or password is incorrect

Common Failures and Solutions:

Error	Cause	Solution
Connection timeout	Network/firewall issue	Check network, firewall rules
401 Unauthorized	Invalid credentials	Verify username/password
403 Forbidden	Insufficient permissions	Ensure user has Admin access
404 Not Found	Incorrect URL	Verify PlentyONE URL
SSL Certificate Error	Invalid/expired certificate	Check SSL certificate validity

If Test Fails

Fix the error, update your credentials in SoftCommerce → PlentyONE → Manage Client Connection (or run bin/magento plenty:client:wizard to reconfigure via CLI), then run the wizard again.

Step 2: Collect Configuration Data

Purpose: Automatically fetch essential configuration data from your PlentyONE system.

What Gets Collected

The wizard collects configuration data for multiple modules:

Module	Data Collected	Purpose
Warehouses	Warehouse list, IDs, names	Stock/inventory mapping
Shipping Providers	Carrier codes, names	Shipping method mapping
Payment Methods	Payment method IDs, names	Payment method mapping
Order Statuses	Status IDs, names, types	Order status mapping
Order Referrers	Referrer IDs, names	Order source tracking
VAT Rates	VAT configurations, rates	Tax calculation
Units	Measurement units	Product unit mapping
Manufacturers	Manufacturer list	Brand mapping
Salesprices	Price configurations	Multi-price support
Attributes	Attribute types, values	Attribute mapping

Total Items: 10-20 configuration collectors (depends on installed modules)

How It Works

Display Available Collectors: Wizard shows all configuration items to be collected
User Initiates Collection: Click "Start Collection"
Sequential Processing: Each collector runs one at a time
Real-Time Progress: Status updates as each item is collected
Error Handling: If a collector fails, wizard logs the error but continues
Completion: All items processed, results displayed

Review Collection List: See what configuration data will be collected
Click "Start Collection": Begins the collection process
Monitor Progress: Watch as each configuration type is collected
Wait for Completion: Takes 30-60 seconds depending on data volume

Visual Progress Indicator

Loading available collectors...

✓ Warehouses            [Collected]
✓ Shipping Providers    [Collected]
⚠ Payment Methods       [Failed - Invalid API response]
✓ Order Statuses        [Collected]
⏳ Order Referrers      [Loading...]
⌛ VAT Rates            [Pending]
⌛ Units                [Pending]
⌛ Manufacturers        [Pending]
⌛ Salesprices          [Pending]
⌛ Attributes           [Pending]

Progress: 4/10 collectors completed

Status Indicators:

⌛ Pending - Waiting to be processed
⏳ Loading - Currently collecting
✓ Collected - Successfully completed
⚠ Failed - Collection failed (hover for error details)

Handling Errors

If one or more collectors fail:

Review Error: Hover over the failed item to see the error message
Common Causes:
- API timeout (increase request timeout)
- Missing permissions (verify user has Admin access)
- Invalid response format (check PlentyONE API version)
- Empty configuration (e.g., no warehouses defined)
Options:
- Continue Anyway: Non-critical failures won't block setup
- Fix and Re-run: Address the issue and restart the wizard
- Manual Configuration: Configure failed items manually later

Non-Blocking Errors

Most configuration collection errors are non-critical. You can proceed with the wizard and manually configure failed items later.

Where Data Is Stored

Collected configuration is stored in:

Database tables: softcommerce_plenty_*_config
Cache: var/cache/plenty/config/
Configuration scope: Global (applies to all stores)

Step 3: Create Required Properties

Purpose: Create necessary properties in PlentyONE for Magento integration.

What Are Properties?

PlentyONE properties are custom fields that store additional data on products, variants, and orders. Mage2Plenty uses specific properties to map Magento data to PlentyONE.

Required Properties:

Property	Type	Purpose	Example Value
Magento Product ID	Item	Links PlentyONE items to Magento products	`12345`
Magento Variation ID	Variation	Links PlentyONE variations to Magento variants	`67890`
Magento Category IDs	Item	Maps PlentyONE items to Magento categories	`10,25,42`
Magento Attribute Set	Item	Stores Magento attribute set ID	`4`
Magento Order ID	Order	Links PlentyONE orders to Magento orders	`100001234`
Magento Customer ID	Contact	Links PlentyONE contacts to Magento customers	`456`

Total Properties: 6-12 properties (depends on installed modules)

How It Works

Check Existing Properties: Wizard verifies which properties already exist in PlentyONE
Display Property List: Shows properties to be created (existing properties marked as "Exists")
User Initiates Creation: Click "Create Properties"
Sequential Creation: Each property is created one at a time via API
Skip Existing: Properties that already exist are skipped
Completion: All properties created or verified

Review Property List: See which properties will be created
Note Existing Properties: Properties marked "Exists" will be skipped
Click "Create Properties": Begins property creation
Monitor Progress: Watch as each property is created
Wait for Completion: Takes 10-30 seconds

Visual Progress Indicator

Loading available properties...

✓ Magento Product ID       [Exists]
✓ Magento Variation ID     [Created]
⏳ Magento Category IDs    [Creating...]
⌛ Magento Attribute Set   [Pending]
⌛ Magento Order ID        [Pending]
⌛ Magento Customer ID     [Pending]

Progress: 2/6 properties processed

Handling Errors

If property creation fails:

Review Error: Hover over the failed item for error details
Common Causes:
- Insufficient API permissions
- Property name conflict
- API rate limiting
- Invalid property configuration
Solutions:
- Retry: Re-run the wizard to retry failed properties
- Manual Creation: Create properties manually in PlentyONE backend
- Check Permissions: Verify API user has property creation rights

Critical Step

Properties are essential for data mapping. If property creation fails, data synchronization won't work correctly. Ensure all properties are created before proceeding.

Verifying Properties in PlentyONE

After wizard completion, verify properties exist:

Log in to PlentyONE backend
Navigate to Setup → Item → Properties
Search for "Magento" properties
Verify all required properties exist

Step 4: Review & Complete Setup

Purpose: Review setup results and finalize the initial configuration.

What Happens

The wizard displays a summary of all completed actions:

✓ API connection tested successfully
✓ Configuration data collected (X/Y collectors successful)
✓ Properties created (X/Y properties created or verified)

Summary Display

Setup Completed Successfully!

✓ API Connection
  - Server: https://mystore.plentymarkets-cloud.com
  - Client ID: 12345
  - Status: Connected
  - Response Time: 0.85s

✓ Configuration Collection
  - Total Collectors: 10
  - Successful: 9
  - Failed: 1 (Payment Methods - non-critical)
  - Data Cached: Yes

✓ Property Creation
  - Total Properties: 6
  - Created: 4
  - Already Existed: 2
  - Status: Ready for synchronization

All required configurations have been created.

Next Steps Guidance

The wizard provides guidance on what to do next:

Next Steps:

✓ Configure your synchronization profiles
✓ Map Magento attributes to PlentyONE properties
✓ Set up cron jobs for automatic synchronization
✓ Run your first data synchronization test

Review Summary: Check all setup results
Note Any Warnings: Address any failed items if needed
Click "Complete Setup": Finalizes the wizard
Redirect: Automatically redirected to Profile Management page

What Happens on Completion

When you click "Complete Setup":

Mark Wizard Complete: Sets setup status to "completed"
Clear Temporary Data: Removes wizard progress data
Log Success: Records successful setup in logs
Redirect: Sends you to SoftCommerce → PlentyONE → Profiles

Post-Setup

After completing the wizard, the next step is to create and configure your first synchronization profile. Start with a simple profile like "Category Import" to verify everything works.

Re-running the Wizard

When to Re-run

You may need to re-run the wizard if:

✅ Switching to a different PlentyONE system
✅ After purging all data
✅ Major configuration changes in PlentyONE
✅ New modules installed that require setup
✅ Properties were manually deleted from PlentyONE

Warning for Completed Setup

If setup was previously completed, the wizard shows a warning:

⚠ Warning: Initial setup has already been completed.

You can still review and update configurations, but this may overwrite existing data.

Options:
- Continue with wizard (updates configuration)
- Cancel (keep existing configuration)
- Purge data first (start completely fresh)

How to Re-run

Navigate to System → PlentyONE → Initial Setup
Review the warning message
Click "Start Setup Wizard" to proceed
Follow the same 4 steps as initial setup

Configuration Updates

Re-running the wizard updates existing configuration but does not delete synchronized data (products, orders, etc.). Only configuration metadata is updated.

Troubleshooting

Wizard Won't Start

Problem: Clicking "Run Setup Wizard" does nothing or shows error

Solutions:

Clear cache: bin/magento cache:flush
Check module is enabled: bin/magento module:status SoftCommerce_PlentyProfile
Verify admin user permissions
Check browser console for JavaScript errors
Review var/log/system.log for PHP errors

Step 1 Connection Test Fails

Problem: Connection test fails repeatedly

Solutions:

Verify authentication credentials in SoftCommerce → PlentyONE → Manage Client Connection
Test connection via CLI: bin/magento plenty:client:test
Test URL manually in browser: https://your-url.com/rest
Check firewall allows HTTPS outbound connections
Enable verbose cURL mode for detailed error in REST API settings
Review var/log/softcommerce/plenty/client.log

Step 2 Collectors Failing

Problem: Multiple configuration collectors fail

Solutions:

Check API user has Admin permissions in PlentyONE
Verify PlentyONE API version is supported
Increase request timeout in REST API settings (increase to 120 seconds)
Check PlentyONE has data for collectors (e.g., warehouses exist)
Review individual error messages (hover over failed items)

Step 3 Property Creation Fails

Problem: Properties won't create in PlentyONE

Solutions:

Verify API user has property creation permissions
Check for existing properties with same name in PlentyONE
Manually create properties in PlentyONE backend
Check PlentyONE API rate limits
Review var/log/softcommerce/plenty/property.log

Wizard Hangs or Freezes

Problem: Wizard stops responding during processing

Solutions:

Check browser console for JavaScript errors
Increase PHP max_execution_time: php.ini → max_execution_time = 300
Increase PHP memory_limit: php.ini → memory_limit = 512M
Clear browser cache and cookies
Try different browser
Check web server error logs

Cannot Complete Wizard

Problem: "Complete Setup" button doesn't work

Solutions:

Check all previous steps completed successfully
Verify form validation passes
Check browser console for errors
Clear cache: bin/magento cache:flush
Review var/log/system.log

Advanced Options

Running via CLI

For automation or troubleshooting, you can run wizard steps via CLI:

# Configure client connection and API settings
bin/magento plenty:client:wizard

# Configure profile system and notifications
bin/magento plenty:profile:wizard

# Run system health check
bin/magento plenty:system:check

# Test connection
bin/magento plenty:client:test

# Collect all configuration
bin/magento plenty:config:collect --all

# Collect specific configuration
bin/magento plenty:config:collect --type=warehouse
bin/magento plenty:config:collect --type=shipping

# Create properties
bin/magento plenty:property:create --all

# Create specific property
bin/magento plenty:property:create --type=product_id

# Mark setup as complete
bin/magento plenty:setup:complete

# Reset setup status (for re-running)
bin/magento plenty:setup:reset

CLI Setup Wizards

The bin/magento plenty:client:wizard and bin/magento plenty:profile:wizard commands provide an interactive CLI experience for configuring client credentials, system settings, and profile system setup. Run both wizards for first-time setup before running the UI Initial Setup Wizard. See CLI Commands Documentation for detailed usage.

Skipping Wizard

If you prefer manual configuration:

Configure authentication via CLI wizards: bin/magento plenty:client:wizard and bin/magento plenty:profile:wizard, or manually in SoftCommerce → PlentyONE → Manage Client Connection
Run configuration collectors individually: bin/magento plenty:config:collect --type=[type]
Create properties manually in PlentyONE backend or via CLI
Skip wizard and proceed directly to profile configuration

Wizard Logs

Log Locations

var/log/softcommerce/plenty/
├── client.log           # Connection tests
├── config.log          # Configuration collection
├── property.log        # Property creation
└── system.log          # General wizard operations

Viewing Logs

# View recent wizard activity
tail -f var/log/softcommerce/plenty/client.log

# Search for errors
grep -i "error" var/log/softcommerce/plenty/*.log

# View last 100 lines of all logs
tail -100 var/log/softcommerce/plenty/*.log

Security Considerations

Wizard Access Control

The wizard requires specific admin permissions:

ACL Resource: SoftCommerce_PlentyProfile::setup_wizard
Required Role: Admin

Restricting Access:

Navigate to System → Permissions → User Roles
Select role to configure
Expand Role Resources
Locate Soft Commerce → PlentyONE Profile → Setup Wizard
Uncheck to deny access

API Credentials Security

The wizard uses credentials stored in configuration:

Credentials are encrypted in database
Never logged in plain text
Transmitted over HTTPS only
Access restricted to authorized users

Performance Considerations

Wizard Duration

Step	Typical Duration	Factors
Step 1: Connection Test	2-5 seconds	Network latency
Step 2: Configuration Collection	30-90 seconds	Number of collectors, data volume
Step 3: Property Creation	10-30 seconds	Number of properties
Step 4: Review & Complete	2-5 seconds	-
Total	45-130 seconds	Network, server speed, data volume

Optimization Tips

Run During Off-Peak: Run wizard when PlentyONE API is less busy
Good Network: Ensure stable, fast internet connection
Server Resources: Ensure adequate PHP memory and execution time
Cache Warm-Up: Clear Magento cache before running wizard

Post-Wizard Next Steps

After successfully completing the wizard:

📊 Create Profiles - Set up your first synchronization profile
🗺️ Attribute Mapping - Map Magento attributes to PlentyONE properties
🔄 Schedule Synchronization - Set up cron jobs for automatic sync
✅ Test Synchronization - Run a test synchronization
📈 Monitor Performance - Track profile execution

Video Tutorial

Outdated Content

This video shows a previous version of the connection configuration. While the core concepts and form fields remain similar, the interface and workflow have been updated. Follow the written documentation above for current instructions.

What's Still Relevant:

✅ Client credential configuration concepts
✅ Connection testing process
✅ Required field explanations
✅ PlentyONE backend configuration

What's Changed:

❌ New CLI wizards available (bin/magento plenty:client:wizard and bin/magento plenty:profile:wizard)
❌ Updated admin menu structure (SoftCommerce → PlentyONE)
❌ Enhanced validation and error handling
❌ Improved token management workflow

Client Configuration - Manual authentication setup
Profile Configuration - Profile system settings
Create Profiles - Setting up synchronization profiles
Troubleshooting - Common issues and solutions
Best Practices - Recommended setup procedures

Getting Help

If you encounter issues with the Initial Setup Wizard:

📧 Email Support: support@softcommerce.io
📞 Phone: +44 2080 587 795 (GMT working hours)
📖 Documentation: Browse this site for detailed guides
🐛 Bug Reports: GitHub Issues

Include in your support request:

Wizard step where error occurred
Error message displayed
Contents of var/log/softcommerce/plenty/ logs
PHP version and Magento version
Screenshot of the error (if applicable)

Overview​

Prerequisites​

Accessing the Wizard​

Method 1: Via Configuration Page​

Method 2: Via Direct URL​

Method 3: Via CLI Wizards​

Step 1: Client Connection & API Configuration​

Step 2: Profile System Setup​

Wizard Steps​

Step 1: Test API Connection​

What Happens​

User Actions​

Possible Outcomes​

Step 2: Collect Configuration Data​

What Gets Collected​

How It Works​

User Actions​

Visual Progress Indicator​

Handling Errors​

Where Data Is Stored​

Step 3: Create Required Properties​

What Are Properties?​

How It Works​

User Actions​

Visual Progress Indicator​

Handling Errors​

Verifying Properties in PlentyONE​

Step 4: Review & Complete Setup​

What Happens​

Summary Display​

Next Steps Guidance​

User Actions​

What Happens on Completion​

Re-running the Wizard​

When to Re-run​

Warning for Completed Setup​

How to Re-run​

Troubleshooting​

Wizard Won't Start​

Step 1 Connection Test Fails​

Step 2 Collectors Failing​

Step 3 Property Creation Fails​

Wizard Hangs or Freezes​

Cannot Complete Wizard​

Advanced Options​

Running via CLI​

Skipping Wizard​

Wizard Logs​

Log Locations​

Viewing Logs​

Security Considerations​

Wizard Access Control​

API Credentials Security​

Performance Considerations​

Wizard Duration​

Optimization Tips​

Post-Wizard Next Steps​

Video Tutorial​

Related Documentation​

Getting Help​

Overview

Prerequisites

Accessing the Wizard

Method 1: Via Configuration Page

Method 2: Via Direct URL

Method 3: Via CLI Wizards

Step 1: Client Connection & API Configuration

Step 2: Profile System Setup

Wizard Steps

Step 1: Test API Connection

What Happens

User Actions

Possible Outcomes

Step 2: Collect Configuration Data

What Gets Collected

How It Works

User Actions

Visual Progress Indicator

Handling Errors

Where Data Is Stored

Step 3: Create Required Properties

What Are Properties?

How It Works

User Actions

Visual Progress Indicator

Handling Errors

Verifying Properties in PlentyONE

Step 4: Review & Complete Setup

What Happens

Summary Display

Next Steps Guidance

User Actions

What Happens on Completion

Re-running the Wizard

When to Re-run

Warning for Completed Setup

How to Re-run

Troubleshooting

Wizard Won't Start

Step 1 Connection Test Fails

Step 2 Collectors Failing

Step 3 Property Creation Fails

Wizard Hangs or Freezes

Cannot Complete Wizard

Advanced Options

Running via CLI

Skipping Wizard

Wizard Logs

Log Locations

Viewing Logs

Security Considerations

Wizard Access Control

API Credentials Security

Performance Considerations

Wizard Duration

Optimization Tips

Post-Wizard Next Steps

Video Tutorial

Related Documentation

Getting Help