Automation

Automate financial tasks and workflows in Firefly III

Firefly III provides powerful automation features to reduce manual data entry and streamline your financial management workflows.

Automation overview

Firefly III offers several automation mechanisms:

Rules

Automatically modify transactions based on triggers

Recurring transactions

Automatically create repeated transactions

Webhooks

Trigger external services on events

Cron jobs

Schedule automated tasks

Rule-based automation

Rules automatically process transactions based on triggers and actions. Rules are powerful for:

• Auto-categorizing transactions
• Setting budgets automatically
• Adding tags based on patterns
• Modifying descriptions
• Converting transaction types

Rule execution

Rules can execute:

On import

Automatically applied when importing transactions from external sources

On manual entry

Triggered when you manually create or edit transactions

Manually

Run rules on existing transactions on demand

For detailed information about creating and managing rules, see Rules documentation

Recurring transaction automation

Recurring transactions automate the creation of repeating transactions like:

• Salary deposits
• Rent payments
• Subscription fees
• Bill payments

Recurrence patterns

Supported recurrence patterns include:

• Daily: Every N days
• Weekly: Every N weeks on specific days
• Monthly: Every N months on specific dates
• Yearly: Every N years on specific dates
• nth weekday: E.g., “first Monday of each month”

Execution timing

Recurring transactions are processed:

1. Via cron: Automatically when cron job runs (recommended)
2. On demand: Manually trigger via web interface
3. Via API: Programmatically trigger creation

Recurring transactions are created slightly ahead of their due date to ensure they appear in your records on time

Learn more in Recurring Transactions documentation

Cron jobs

Firefly III uses scheduled tasks (cron jobs) to automate background processes.

Required cron job

For full automation, set up this cron job:

Docker

# Already configured in Docker containers
# Runs every hour automatically

Automated tasks

The cron job handles:

Recurring transactions

Creates new transactions from active recurrences based on their schedule

Bill matching

Matches transactions to bills automatically based on amount and description patterns

Webhook delivery

Retries failed webhook deliveries

Exchange rate updates

Fetches current exchange rates if configured

Telemetry collection

Collects anonymous usage statistics if enabled

Cache cleanup

Clears expired cache entries

Manual execution

You can manually run scheduled tasks:

php artisan schedule:run

Or trigger specific tasks:

# Process recurring transactions
php artisan firefly-iii:create-recurring-transactions

# Match bills
php artisan firefly-iii:match-bills

Use manual execution for testing or troubleshooting before setting up cron

Import automation

While Firefly III itself doesn’t import from banks automatically, you can use external tools:

Data Importer

The official Firefly III Data Importer can:

• Import from bank CSV files
• Connect to bank APIs (via Salt Edge or Nordigen)
• Import from other Firefly III instances
• Schedule automatic imports

Third-party tools

Community tools for automation:

• plaid2ff3: Import from Plaid
• ynab-to-firefly: Migrate from YNAB
• nordigen-firefly: Direct Nordigen integration
• saltedge-firefly: Salt Edge integration

See the data import documentation for more details

API automation

You can build custom automation using the Firefly III API:

Common automation patterns

Transaction creation

# Automatically create transactions from external events
curl -X POST "https://your-firefly.local/api/v1/transactions" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "transactions": [{
      "type": "withdrawal",
      "date": "2024-01-01",
      "amount": "50.00",
      "description": "Automated transaction",
      "source_name": "Checking Account",
      "destination_name": "Groceries"
    }]
  }'

Budget monitoring

# Check budget spending and trigger alerts
curl -X GET "https://your-firefly.local/api/v1/budgets/1/limits" \
  -H "Authorization: Bearer YOUR_TOKEN"

# Process response and send alert if over budget

Report generation

# Generate automated reports
curl -X GET "https://your-firefly.local/api/v1/insight/expense/total?start=2024-01-01&end=2024-01-31" \
  -H "Authorization: Bearer YOUR_TOKEN"

See the API documentation for complete endpoint reference

Best practices

Test automation first

Always test automation rules and scripts on a small dataset before applying to all transactions. Use rule testing features and backup your database.

Monitor automated processes

Regularly check:

• Rule execution logs
• Recurring transaction creation
• Webhook delivery status
• Cron job execution logs

Use rule groups strategically

Organize rules into groups by purpose:

• Import rules (run first)
• Categorization rules
• Cleanup rules (run last)

Keep rules simple

Create multiple simple rules rather than few complex ones. This makes debugging easier and improves performance.

Document your automation

Use descriptive rule names and add notes about what each automation does and why.

Review periodically

Quarterly review of:

• Rule effectiveness
• Recurring transaction accuracy
• Automation performance
• Unused or redundant rules

Advanced automation scenarios

Multi-stage processing

Combine multiple automation features:

1. Import transactions

   Use Data Importer to fetch bank transactions automatically

2. Apply rules

   Rules automatically categorize and tag imported transactions

3. Trigger webhooks

   Webhooks notify external services of new transactions

4. Generate alerts

   External service checks budgets and sends alerts if needed

Conditional processing

Use rule conditions for smart automation:

• Apply different categories based on amount ranges
• Set budgets only for specific account types
• Add tags based on time of day or day of week
• Convert transaction types based on source/destination

Integration with external tools

Zapier/n8n

Connect Firefly III to 1000+ services using workflow automation platforms

Home Assistant

Integrate with smart home for location-based expense tracking

IFTTT

Create simple if-this-then-that automations

Custom scripts

Build Python/Node.js scripts using the API

Troubleshooting

Cron not running

Problem: Scheduled tasks aren’t executing

Solutions:

• Check cron is installed and running: systemctl status cron
• Verify crontab entry: crontab -l
• Check logs: grep CRON /var/log/syslog
• Ensure PHP CLI is available
• Check file permissions on artisan file

Rules not applying

Problem: Rules aren’t processing transactions

Solutions:

• Verify rule is active
• Check “Apply rules” is enabled in preferences
• Test rule with rule tester
• Review rule execution order
• Check for conflicting rules

Recurring transactions not created

Problem: Recurring transactions aren’t being generated

Solutions:

• Check recurrence is active
• Verify next expected run date
• Ensure cron job is running
• Check for errors in logs
• Manually trigger to test: php artisan firefly-iii:create-recurring-transactions

Related documentation

Rules

Detailed rule configuration

Recurring transactions

Set up repeating transactions

Webhooks

External integrations

API

Build custom automation