ICS Calendar Integration

Task Genius provides powerful ICS calendar integration to display external calendar events in your task views, with advanced holiday detection, status mapping, and text processing capabilities.

Available since 9.0.0

Overview

The ICS integration allows you to:

Import calendar events from external ICS/iCal sources
Detect and group holidays to reduce visual clutter
Map events to task statuses based on timing and properties
Transform event text using custom replacement rules
Display events in forecast and calendar views alongside your tasks

Getting started

Basic setup

Go to Settings → Task Genius → ICS Calendar Integration
Configure global settings for refresh intervals and caching
Add your first calendar source by clicking Add New Calendar Source

Adding a calendar source

When adding a new source, you'll need to configure:

Source name: Display name for the calendar
ICS URL: The URL to your ICS/iCal file
Refresh interval: How often to sync (in minutes)
Color: Optional color for events from this source
Show type: Display as "Event" or "Badge" in calendar views

Supported URL types

Google calendar: Use the public ICS URL from calendar settings
Outlook/Office 365: Export calendar and use the ICS URL
CalDAV: Any CalDAV-compatible calendar service
File URLs: Local or network file paths to ICS files

Authentication

For private calendars, configure authentication:

Basic auth: Username and password
Bearer token: API token authentication
Custom headers: Custom HTTP headers for specialized services

Holiday detection & grouping

Overview

Holiday detection automatically identifies and groups consecutive holiday events to reduce clutter in your calendar views.

Configuration

Enable holiday detection in your calendar source settings:

{
  "enabled": true,
  "groupingStrategy": "first-only",
  "maxGapDays": 1,
  "showInForecast": true,
  "showInCalendar": true
}

Grouping strategies

None: Show all events individually
First only: Show only the first day of consecutive holidays
Summary: Show a summary with day count (e.g., "Holiday (3 days)")
Range: Show first and last days (e.g., "Holiday: May 1-3")

Detection patterns

Configure patterns to identify holiday events:

Summary patterns (Regex)

Regular expressions to match event titles:

holiday
christmas
day\s+\d+
\d+\s+days?
day\s+\d+\s+of\s+\d+

Keywords

Simple text matching:

holiday
vacation
christmas
festival

Example: Multi-day holiday calendar

For holiday calendars showing "Christmas Holiday Day 1 of 3", "Christmas Holiday Day 2 of 3", etc.:

Enable holiday detection
Set grouping strategy to "First only"
Add detection patterns:
- Summary: holiday, day\s+\d+, \d+\s+days?
- Keywords: holiday, christmas
Configure display: Show only the first day to avoid repetition

Status mapping

Overview

Status mapping automatically assigns task statuses to ICS events based on timing and event properties, integrating with your existing task status system.

Basic configuration

Enable status mapping in your calendar source:

{
  "enabled": true,
  "overrideIcsStatus": true,
  "timingRules": {
    "pastEvents": "x",
    "currentEvents": "/",
    "futureEvents": " "
  }
}

Timing rules

Map events based on when they occur:

Past events: Events that have ended (default: "x" - Complete)
Current events: Events happening today (default: "/" - In Progress)
Future events: Events in the future (default: " " - Incomplete)

Property rules (Higher priority)

Override timing rules based on event properties:

Holiday mapping

{
  "holidayMapping": {
    "holidayStatus": "-"
  }
}

Maps detected holidays to "Cancelled" status to hide from active tasks.

Category mapping

Map specific event categories:

holiday:-
vacation:-
festival:-
meeting:/
work:x

Summary pattern mapping

Use regex patterns to map based on event titles:

Pattern: ^Meeting: → Status: / (In Progress)
Pattern: holiday.*day\s+\d+ → Status: - (Cancelled)

Integration with task status system

Status mapping uses your existing task status configuration:

Maps to status marks defined in plugin settings
Falls back to default marks if custom marks not found
Respects your task counting and progress calculation rules

Text replacements

Overview

Transform event text using regular expressions to clean up or standardize event titles, descriptions, and locations.

Creating replacement rules

In your calendar source settings, scroll to "Text Replacements"
Click "Add Text Replacement Rule"
Configure the rule:
- Rule name: Descriptive name
- Target field: Summary, Description, Location, or All
- Pattern: Regular expression to match
- Replacement: Text to replace with (use $1, $2 for capture groups)
- Flags: Regex flags (e.g., "g" for global, "i" for case-insensitive)

Common examples

Remove meeting prefix

Pattern: ^Meeting:
Replacement: `` (empty)
Result: "Meeting: Weekly Standup" → "Weekly Standup"

Replace room numbers

Pattern: Room (\d+)
Replacement: Conference Room $1
Result: "Room 101" → "Conference Room 101"

Clean holiday text

Pattern: holiday.*day\s+\d+\s+of\s+\d+
Replacement: holiday
Result: "Christmas holiday day 1 of 3" → "Christmas holiday"

Swap words

Pattern: (\w+) with (\w+)
Replacement: $2 and $1
Result: "Meeting with John" → "John and Meeting"

Testing rules

Use the built-in test feature when creating rules:

Enter sample text in the "Test Input" field
See the transformed result in real-time
Adjust pattern and replacement as needed

Use cases & examples

1. Work calendar integration

Scenario: Integrate work calendar with meetings and deadlines

Configuration:

Timing rules: Past meetings → Complete, Current → In Progress, Future → Incomplete
Category mapping: meeting:/, deadline:!
Text replacements: Remove "Meeting:" prefix, standardize room names

Result: Clean integration with task workflow, proper status tracking