BetterMacro User Guide
Introduction
BetterMacro is a multi-tenant automation platform designed to streamline Linnworks order processing workflows. Each Linnworks account gets its own completely isolated workspace with zero cross-contamination between users.
Key Features
Automated Order Processing: Set up automated schedules to process orders at regular intervals
Multi-Tenant Security: Complete data isolation with no cross-user access
Real-time Monitoring: Track processing status with comprehensive dashboards
Flexible Scheduling: From minute-by-minute to daily processing schedules
Duplicate Prevention: Prevent orders from being processed multiple times
Custom Processing Steps: Configure exactly what happens to each order
Alert Notifications: Email alerts for processing failures and completion
Getting Started
Before using BetterMarco, ensure you have:
A valid Linnworks account with API access
Linnworks Application ID and Secret
Admin privileges in your Linnworks account
Email address for notifications
First-Time Setup
Access the Application: Navigate to the BetterMacro URL in your web browser
Authentication: Click "Create Your Isolated Workspace" to begin setup
Linnworks Connection: Provide your Linnworks credentials when prompted
Workspace Creation: The system will create your isolated workspace automatically
Authentication - Multi-Tenant Security Model
BetterMacro implements a secure multi-tenant architecture where:
Each Linnworks account gets its own isolated database space
No user can see or access another user's data
All data is encrypted and separated at the database level
Each session is validated against your specific Linnworks account
Authentication Process
Initial Login: Provide your Linnworks Application ID and Secret
Token Generation: The system generates a secure session token
Automatic Re-authentication: Sessions are renewed automatically when possible
Security Validation: Every API call is validated against your credentials
Session Management
Sessions remain active during use and renew automatically
If authentication fails, you'll be prompted to re-authenticate
Logout is available in the header menu
Multiple devices can be logged in simultaneously
Dashboard Overview
The BetterMacro dashboard consists of two main sections:
1. Dashboard Tab
Purpose: Monitor active Processes, view logs and control global settings
Features:
Processing Status: Real-time view of running processes
Recent Logs: Live feed of processing activities
Performance Metrics: Success rates and processing statistics
Debug Controls: Global debug logging toggle
System Health: Overall system status monitoring
2. Configuration Tab
Purpose: Create, edit and manage your automation macros
Features:
Macro Management: Create, edit, delete, and organize macros
Location Settings: Configure source and target locations
Processing Steps: Define what happens to each order
Scheduling Options: Set up automated execution
Advanced Settings: Duplicate prevention, time windows, and more
Creating and Managing Macros
What is a Macro?
A macro is a set of automated instructions that define:
Which orders to process (source location, time frame, filters)
What to do with those orders (move, label, set properties)
When to run the automation (schedule)
How to prevent duplicates
Creating a New Macro
Navigate to Configuration Tab
Click "Add New Macro"
Basic Settings:
Name: Descriptive name for your macro
Description: Optional details about the macro's purpose
Enable/Disable: Toggle to activate the macro
Location Configuration:
Source Location: Where orders currently exist
Target Location: Where orders should be moved (optional)
Time Frame Settings:
Last X Days: Process orders from the past X days
Custom Days: Specify exact number of days
Time Window: Optional time range filtering
Processing Steps Configuration:
Change Location: Move orders to target location
Create Labels: Generate shipping labels
Set Properties: Add extended properties to orders
Process Order: Mark orders as processed
Managing Existing Macros
Edit: Click the edit button to modify macro settings
Enable/Disable: Toggle macros on/off without deleting
Duplicate: Clone existing macros as templates
Delete: Remove macros permanently (with confirmation)
Reorder: Drag and drop to organise macro list
Configuration Settings
Location Settings
Configure which Linnworks locations to use:
Source Location (From):
The location where orders currently exist
System will search this location for matching orders
Target Location (To):
Optional destination for order movement
Leave blank if you don’t want to move orders
Must be different from source location
Time Frame Settings
Control which orders are processed based on date:
Options:
Last 1 Day: Orders from yesterday
Last 3 Days: Orders from past 3 days
Last 7 Days: Orders from past week
Custom Days: Specify exact number of days
Time Windows (Advanced):
Between: Process orders only between specific times
Before: Process orders only before a specific time
After: Process orders only after a specific time
Skip Current Day: Exclude today's orders from processing
Processing Steps
Define exactly what happens to each matched order:
1. Change Location
Purpose: Move orders from source to target location
When to Use: Order fulfillment workflows, location organization
Requirements: Target location must be different from source
2. Create Labels
Purpose: Generate shipping labels for orders
Templates: Select from available Linnworks label templates
Automation: Labels are created automatically for each order
3. Set Properties
Purpose: Add extended properties to orders for tracking
Custom Properties: Define property name and value
Use Cases: Tracking, reporting, integration with other systems
4. Process Order
Purpose: Mark orders as processed in Linnworks
Effect: Changes order status to processed/completed
Final Step: Usually the last step in most workflows
Duplicate Prevention
Prevent orders from being processed multiple times:
How It Works:
System adds a special property to processed orders
Before processing, checks if order already has this property
Skips orders that have already been process
Settings:
Enable/Disable: Turn duplicate prevention on/off
Property Name: Name of the tracking property (auto-generated)
Per-Macro: Each macro uses its own tracking property
Property Settings
Add custom extended properties to processed orders:
Configuration:
Property Name: The name of the property to set
Property Value: The value to assign to the property
Use Cases: Order tracking, custom workflows, reporting
Advanced Properties:
Multiple Properties: Configure multiple properties per macro
Dynamic Values: Use placeholders for dynamic content
Data Types: Support for strings, numbers, dates, booleans
Alers Settings
Configure email notifications for macro execution:
Email Addresses:
Add multiple email addresses for notifications
Supports both success and failure alerts
Emails include detailed processing information
Alert Types:
Completion Alerts: Sent when macro competes successfully
Error: Sent when macro encounters errors
Authentication Alerts: Sent when re-authentication is required
Monitoring and Logos
Real-Time Processing Logs
The Dashboard tab provides live monitoring of all processing activities:
Log Levels:
Info: General processing information
Success: Successful operations
Warning: Non-critical issues
Error: Failed operations requiring attention
Log Details Include:
Timestamp of each operation
Macro name and configuration
Order numbers and details
Processing results and statistics
Error messages and troubleshooting info
Processing Sessions
Each macro execution creates a processing session with:
Session Information:
Start and end times
Total orders processed
Number of errors encountered
Configuration snapshot used
Performance metrics
Session Status:
Running: Currently processing
Completed: Finished successfully
Completed with Errors: Finished but with some failures
Failed: Unable to complete processing
Performance Monitoring
Track the efficiency and reliability of your macros:
Metrics Tracked:
Orders processed per session
Average processing time
Success/failure rates
API call efficiency
Resource utilisation
Performance Optimisation:
Automatic rate limiting to prevent API overload
Circuit breaker pattern for error recovery
Batch processing for large volumes
Performance alerts for unusual activity
Log Retention
To maintain optimal performance:
Processing logs are automatically cleaned up after 48 hours
Session summaries and statistics are preserved permanently
Cleanup runs daily at 2 AM UTC
Performance indexes ensure fast log queries
Scheduling
Automated Scheduling System
BetterMacro uses a sophisticated heartbeat system for reliable automation:
How It Works:
Heartbeat: A cron job runs every minute as a system heartbeat
Check: Each heartbeat checks for macros with scheduling enabled
Calculate: System calculates time since last run vs. frequency setting
Execute: Processes only when timing criteria is met
Record: All execution details are logged for monitoring
Schedule Configuration
Frequency Options
Choose from a wide range of execution frequencies:
High Frequency (Ideal for active processing):
Every 1 minute
Every 2 minutes
Every 5 minutes
Every 10 minutes
Every 15 minutes
Medium Frequency (Balanced approach):
Every 30 minutes
Every 45 minutes
Every 1 hour
Every 2 hours
Low Frequency (Batch processing):
Every 4 hours
Every 8 hours
Every 12 hours
Every 24 hours
Daily at specific time
Daily Scheduling
For daily batch processing:
Configuration:
Select "Daily at specific time" from frequency options
Choose hour (0-23) in UTC time zone
Macro runs once daily at specified time
Benefits:
Predictable processing windows
Ideal for end-of-day batch processing
Reduces resource consumption
Perfect for daily order reconciliation
Schedule Management
Enable/Disable: Toggle scheduling without deleting configuration
Monitor Performance: Track execution times and success rates
Adjust Frequency: Change timing based on processing needs
Time Zone Consideration: All times are in UTC - convert as needed
Best Practices for Scheduling
High-Frequency Processing (≤5 minutes)
Use Case: Real-time order processing, urgent fulfilment
Monitoring: Watch performance closely for resource usage
Recommendation: Start with longer intervals and decrease as needed
Medium-Frequency Processing (30min - 2hrs)
Use Case: Regular processing without overwhelming the system
Balance: Good compromise between speed and efficiency
Recommendation: Most common choice for general automation
Low-Frequency Processing (4hrs+)
Use Case: Batch processing, end-of-day operations
Benefits: Lower resource usage, predictable processing windows
Recommendation: Use for non-urgent bulk operations
Advanced Features
Multiple Macros
Run multiple macros simultaneously:
Each macro operates independently
Different schedules for different workflows
Isolated processing to prevent conflicts
Individual monitoring and logging
Blocked Dates
Prevent processing on specific dates:
Holiday Processing: Skip processing on holidays
Maintenance Windows: Avoid processing during system maintenance
Custom Blackouts: Define any dates to skip processing
Flexible Configuration: Per-macro date exclusions
Time Window Filtering
Process orders only within specific time ranges:
Window Types:
Between: Process orders placed between two times
Before: Process orders placed before a specific time
After: Process orders placed after a specific time
Use Cases:
Business hours processing
Timezone-specific handling
Order type segregation
Custom workflow requirements
Extended Properties Management
Advanced property configuration:
Multiple Properties: Set multiple extended properties per order
Dynamic Values: Use order data to populate property values
Property Types: Support for various data types
Conditional Logic: Set properties based on order characteristics
Large Volume Optimisation
BetterMacro is optimised for processing large volumes:
Performance Features:
Batch processing (10 orders at a time)
Rate limiting (8 API calls per second maximum)
Circuit breaker for error recovery
Performance monitoring and alerting
Automatic retry mechanisms
Volume Recommendations:
Small Volume (1-50 orders): Any frequency works well
Medium Volume (51-200 orders): Consider 5+ minute frequencies
Large Volume (200+ orders): Use hourly or daily scheduling
API Integration
BetterMacro integrates deeply with the Linnworks API:
Supported Operations:
Order search and filtering
Location management
Extended property management
Shipping label generation
Order status updates
Error Handling:
Automatic retry for transient failures
Circuit breaker for API protection
Authentication refresh handling
Detailed error reporting
Common Issues and Solutions
Authentication Errors
Symptoms: "Authentication required" messages, login prompts
Causes: Expired tokens, changed Linnworks credentials, API limits
Solutions:
Re-authenticate using the login prompt
Verify Linnworks Application ID and Secret are correct
Check Linnworks API quota usage
Ensure Linnworks account is active and accessible
Processing Failures
Symptoms: Orders found but processing fails
Causes: API errors, permission issues, invalid configurations
Solutions:
Check processing logs for specific error messages
Verify target location exists and is accessible
Confirm extended property names are valid
Test with a single order manually in Linnworks
Schedule Not Running
Symptoms: Scheduled macro doesn't execute automatically
Causes: Disabled macro, authentication issues, system errors
Solutions:
Verify macro is enabled and schedule is configured
Check authentication status
Review recent logs for error messages
Try manual execution to test configuration
Debugging Features
Debug Logging
Enable detailed logging for troubleshooting:
Location: Dashboard tab → Debug toggle
Effect: Provides additional detail in processing logs
Use: Enable temporarily when investigating issues
Performance: May slightly impact processing speed
Processing Session Details
Every macro execution creates detailed session information:
Configuration Snapshot: Exact settings used
Order Details: Information about each processed order
Error Details: Specific error messages and stack traces
Performance Metrics: Timing and efficiency statistics
Log Analysis
Use processing logs to diagnose issues:
Search: Filter logs by date, macro, or message content
Levels: Focus on specific log levels (errors, warnings)
Patterns: Look for recurring issues or patterns
Timing: Identify performance bottlenecks
Getting Help
Self-Service Resources
Processing Logs: Check recent activity for error messages
Configuration Review: Verify all settings are correct
Manual Testing: Try running macros manually first
Documentation: Refer to this user guide
Support Information
System Status: Monitor for known issues or maintenance
API Limits: Check Linnworks API usage and limits
Account Status: Verify Linnworks account is active
Network: Ensure stable internet connection
Security and Privacy
Data Protection
BetterMacro implements enterprise-grade security measures:
Multi-Tenant Isolation:
Complete data separation between users
Database-level isolation using Row Level Security (RLS)
No shared resources or cross-user access
Individual encryption keys per tenant
Data Encryption:
All data encrypted at rest and in transit
TLS/SSL for all communications
Encrypted database storage
Secure token-based authentication
Access Controls:
Authentication required for all operations
Session-based access with automatic expiration
API rate limiting and abuse prevention
Audit logging for all activities
Privacy Commitment
Data Collection: Only collect data necessary for functionality
Data Sharing: Never share user data with third parties
Data Retention: Automatic cleanup of temporary processing data
User Control: Users control all their data and settings
Linnworks Integration:
Read-only access to order data (except for configured changes)
No storage of sensitive Linnworks credentials
API keys encrypted and stored securely
Minimal data retention policy