Category Import Profile

The Category Import Profile synchronizes category structures from PlentyONE to Magento, creating and updating Magento categories based on your PlentyONE category tree.

Overview

Profile Type ID: plenty_category_import Direction: PlentyONE → Magento Purpose: Import category hierarchy, names, descriptions, and attributes from PlentyONE

What Gets Imported

• Category structure and hierarchy
• Category names (multi-language support)
• Category descriptions
• Category attributes and properties
• Parent-child relationships
• Category status (active/inactive)

Use Cases

• Initial Setup: Import your complete PlentyONE category structure to Magento
• Category Synchronization: Keep Magento categories in sync with PlentyONE changes
• Multi-Language Stores: Sync category translations for different store views
• Category Updates: Automatically update category information when changed in PlentyONE

Configuration Sections

1. Client Configuration

Configure the PlentyONE client connection for this profile.

Client Selection

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

Select the PlentyONE client from which to import categories.

Available Actions:

• Edit: Modify existing client settings
• New Client: Create a new PlentyONE client connection

Configuration Data Management

Collect Configuration Data

Fetches configuration data from PlentyONE, including:

• Available categories
• Category properties
• Locale settings
• Client-specific settings

How to Use:

1. Select a client
2. Click Collect Configuration Data
3. Wait for data collection to complete
4. Configuration data is now available for mapping

Delete Configuration Data

Removes all collected configuration data for the selected client.

Data Removal

Deleting configuration data does not affect actual categories in Magento or PlentyONE. It only removes the cached configuration data used for mappings.

2. Schedule Configuration

Automate category imports with scheduled execution.

Enable Schedule

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

Enable or disable automatic scheduled imports.

Schedule Selection

Field: schedule_id Type: Select (required when schedule enabled) Scope: Global

Select a cron schedule for automatic execution.

Available Actions:

• Edit: Modify the selected schedule
• New Schedule: Create a new cron schedule
• View Schedules: See all scheduled tasks and their next run times

Common Schedule Examples:

Every 15 minutes: */15 * * * *
Every hour:       0 * * * *
Every 6 hours:    0 */6 * * *
Daily at 2 AM:    0 2 * * *

Process Batch Size

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

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

Recommendations:

• Small catalogs (< 500 categories): 100-200
• Medium catalogs (500-2000 categories): 50-100
• Large catalogs (> 2000 categories): 25-50

Performance Tuning

Smaller batch sizes reduce memory usage but increase execution time. Larger batch sizes are faster but consume more memory. Adjust based on your server resources.

Enable History

Field: enable_history Type: Checkbox Default: Yes Scope: Global

Creates execution history records for each profile run, including:

• Start and end times
• Number of categories processed
• Success/failure status
• Error messages and warnings

3. HTTP API Configuration

Configure how the profile interacts with the PlentyONE API.

API Behaviour

Field: api_behaviour Type: Select (required) Default: Append Scope: Global

Defines how imported categories are handled in Magento.

Options:

Value	Behavior	Use Case
Append	Add new categories, update existing ones	Standard synchronization
Replace	Replace all categories with fresh import	Full category reset
Delete	Remove categories that no longer exist in PlentyONE	Cleanup obsolete categories

Recommended: Use Append for regular synchronization to avoid accidental data loss.

API Collection Size

Field: collection_size Type: Text Default: 100 Max: 500 Scope: Global

Number of categories retrieved per API request from PlentyONE.

API Rate Limiting:

• PlentyONE API has rate limits
• Smaller page sizes = more API calls
• Larger page sizes = fewer API calls but more data per call

Recommendations:

• Default: 100 (good balance)
• Fast sync: 250-500 (if API limits allow)
• Rate limit issues: 50-100 (reduce API load)

4. Store Configuration

Map PlentyONE clients to Magento stores for multi-store setups.

Store Mapping

Field: store_mapping Type: Dynamic Rows Scope: Global

Configure which PlentyONE client and locale to use for each Magento store.

Fields per Row:

Field	Type	Description
Store	Select (required)	Magento store view
Client	Select (required)	PlentyONE client for this store
Locale	Select (required)	PlentyONE locale (language)

Example Configuration:

Store	Client	Locale
English Store	PlentyONE Client 1	en
German Store	PlentyONE Client 1	de
French Store	PlentyONE Client 1	fr

Multi-Language Support:

• Each store can use different locales
• Category names/descriptions are imported in the selected language
• Same client can serve multiple stores with different languages

5. Category Configuration

Map categories and attributes between PlentyONE and Magento.

Root Category Mapping

Field: root_category_mapping Type: Dynamic Rows Scope: Global

Map PlentyONE root categories to Magento root categories.

Fields per Row:

Field	Type	Description
Magento Category	Select (required)	Magento root category
PlentyONE Category	Select (required)	PlentyONE root category

Purpose:

• Defines where PlentyONE categories are imported in Magento's category tree
• Multiple PlentyONE categories can be mapped to different Magento roots
• Allows selective category import

Example:

Magento: Default Category → PlentyONE: Main Catalog
Magento: Clearance → PlentyONE: Sale Items
Magento: New Arrivals → PlentyONE: New Products

Create Root Category Button

Opens a modal to create a new root category directly in PlentyONE.

When to Use:

• Setting up new category branches
• Organizing categories for specific purposes
• Creating region-specific category trees

Attribute Mapping

Field: attribute_mapping Type: Dynamic Rows Scope: Global

Map PlentyONE properties to Magento category attributes.

Fields per Row:

Field	Type	Description
Plenty Property	Select (required)	PlentyONE category property
Magento Attribute	Select (required)	Magento category attribute

Common Mappings:

PlentyONE Property	Magento Attribute	Purpose
name	name	Category name
description	description	Category description
meta_title	meta_title	SEO meta title
meta_description	meta_description	SEO meta description
meta_keywords	meta_keywords	SEO keywords
is_active	is_active	Category status

Custom Attributes:

• You can map to custom Magento category attributes
• Create custom attributes in Magento first
• Then map PlentyONE properties to these attributes

6. Log Configuration

Configure detailed logging for debugging and monitoring.

Log Request Data

Field: is_active_request_log Type: Checkbox Default: No Scope: Global

Logs all API request data sent to PlentyONE.

Logged Information:

• Request URL and method
• Request headers
• Request body/payload
• Timestamp

File Location: var/log/softcommerce/plenty/category.log

Performance Impact

Request logging can generate large log files with high-volume imports. Enable only for debugging.

Log Response Data

Field: is_active_response_log Type: Checkbox Default: No Scope: Global

Logs all API response data received from PlentyONE.

Logged Information:

• Response status code
• Response headers
• Response body/data
• Timestamp

When to Enable:

• Debugging import issues
• Investigating data discrepancies
• Troubleshooting API errors
• Monitoring API response times

Configuration Workflow

Initial Setup

1. Create Profile

   • Navigate to SoftCommerce → PlentyONE → Profiles
   • Click Add New Profile
   • Select Category Import as profile type
   • Enter profile name (e.g., "PlentyONE Category Import")

2. Configure Client

   • Select PlentyONE client
   • Click Collect Configuration Data
   • Wait for data collection to complete

3. Configure Store Mapping

   • Add store mappings for each Magento store
   • Select appropriate client and locale for each store

4. Configure Category Mapping

   • Map Magento root categories to PlentyONE categories
   • Configure attribute mappings

5. Set Up Schedule (optional)

   • Enable schedule
   • Select or create cron schedule
   • Set batch size based on catalog size

6. Test Import

   • Save profile
   • Run manual execution: Actions → Execute Now
   • Review imported categories
   • Check execution history for errors

7. Enable Automatic Import

   • Enable schedule (if not already done)
   • Monitor first few scheduled executions
   • Adjust batch size and schedule as needed

Ongoing Maintenance

Regular Tasks:

• Monitor execution history for errors
• Review imported categories for accuracy
• Update attribute mappings when PlentyONE changes
• Adjust schedule frequency based on category update frequency

When Categories Don't Import:

1. Check profile execution history
2. Review error logs in var/log/softcommerce/plenty/category.log
3. Verify root category mappings are correct
4. Ensure collect configuration data is up to date
5. Check API credentials are still valid

CLI Commands

Execute Category Import

# Execute category import profile manually
bin/magento softcommerce:plenty:category:import --profile-id=1

# Execute with specific batch size
bin/magento softcommerce:plenty:category:import --profile-id=1 --batch-size=50

# Execute for specific store
bin/magento softcommerce:plenty:category:import --profile-id=1 --store-id=1

View Category Import History

# View last 10 executions
bin/magento softcommerce:profile:history --id=1 --limit=10

# View executions with errors only
bin/magento softcommerce:profile:history --id=1 --status=error

Collect Configuration Data via CLI

# Collect category configuration data
bin/magento softcommerce:plenty:category:collect-config --client-id=1

# Force re-collection
bin/magento softcommerce:plenty:category:collect-config --client-id=1 --force

Troubleshooting

Categories Not Importing

Problem: Categories from PlentyONE don't appear in Magento

Solutions:

1. Check Root Category Mapping

   • Verify PlentyONE categories are mapped to Magento root categories
   • Ensure Magento root category exists

2. Review API Collection Size

   • Reduce collection size if timeout occurs
   • Increase if import is too slow

3. Verify Store Mapping

   • Ensure store mapping is configured
   • Check client and locale are correct

4. Check Category Status

   • Verify categories are active in PlentyONE
   • Check category visibility settings

Missing Category Names/Descriptions

Problem: Categories import but names or descriptions are missing

Solutions:

1. Check Locale Settings

   • Verify correct locale is selected in store mapping
   • Ensure category data exists for that locale in PlentyONE

2. Review Attribute Mapping

   • Verify name and description are mapped
   • Check mapping is to correct Magento attributes

3. Check PlentyONE Data

   • Verify category has name/description in PlentyONE
   • Check for that specific locale

Duplicate Categories

Problem: Categories are duplicated in Magento

Solutions:

1. Check API Behaviour

   • Set to "Append" (not "Replace")
   • Review behavior setting matches use case

2. Review Root Category Mapping

   • Ensure same PlentyONE category isn't mapped to multiple roots
   • Check for overlapping mappings

3. Clear and Reimport

   • Delete duplicate categories
   • Set API Behaviour to "Replace"
   • Run fresh import
   • Switch back to "Append"

Performance Issues

Problem: Category import is very slow

Solutions:

1. Optimize Batch Size

   • Increase batch size: 150-200
   • Monitor memory usage

2. Optimize API Collection Size

   • Increase to 250-500
   • Monitor for API rate limit issues

3. Schedule During Off-Peak

   • Run imports during low-traffic hours
   • Avoid peak business times

4. Enable Caching

   • Ensure Magento caching is enabled
   • Use Redis for session and cache storage

Best Practices

Initial Import

1. Test with Limited Data: Start with small category tree to test mapping
2. Verify Mappings: Double-check root category and attribute mappings
3. Monitor First Import: Watch the first full import execution
4. Validate Results: Review imported categories in Magento admin

Regular Synchronization

1. Frequent Sync: Schedule imports every 15-60 minutes for real-time updates
2. Off-Peak Execution: Run large imports during low-traffic periods
3. Monitor History: Regularly check execution history for errors
4. Update Mappings: Keep attribute mappings current with PlentyONE changes

Multi-Store Setup

1. Locale Consistency: Ensure locale matches store language
2. Test Per Store: Verify imports work for each store view
3. Shared Clients: Use same client for multiple stores when appropriate
4. Separate Roots: Consider separate root categories per store/region

Performance

1. Batch Size: Adjust based on server resources and catalog size
2. API Limits: Respect PlentyONE API rate limits
3. Error Handling: Enable history to track and resolve errors
4. Log Rotation: Disable request/response logging in production

Related Documentation

• About Profiles
• Creating a Profile
• Category Export Profile
• Troubleshooting Profiles
• CLI Commands