Timeline Regeneration Campaigns

Timeline regeneration campaigns let administrators force GeoPulse to rebuild user timelines from a selected point in time. They are used when an important change in timeline generation logic needs to be applied to existing data, or when a bug corrupted generated timeline entries.

Campaigns can be created in two ways:

Source	Description
RELEASE	Created by GeoPulse developers as part of an application release. Use these when release notes or the Admin Panel show that a release campaign was scheduled automatically.
ADMIN	Created manually by an administrator from the Admin Panel. Use these for instance-specific timeline repair or after an administrator confirms that existing timelines need to be regenerated.

No user action required

Users do not need to manually regenerate their own timelines. When a campaign is created, GeoPulse queues the affected users automatically and processes them in the background. Users may receive a "Timeline refresh scheduled" notification, but the notification is informational.

When to Create a Campaign

Create an admin campaign only when existing generated timeline data is known or strongly suspected to be wrong.

Good reasons include:

• a timeline generation bug produced corrupted stays, trips, or gaps
• an important timeline logic change should be applied to already-generated historical data
• an operational repair requires rebuilding timelines for many users from the same timestamp

Do not create a campaign for routine user preference changes, favorite place changes, or imports that already trigger their own timeline regeneration flow.

How Campaigns Work

1. An admin selects a Regenerate From timestamp.
2. GeoPulse previews the number of users with GPS points at or after that timestamp.
3. After confirmation, GeoPulse creates one campaign entry and one queued work item for each affected user.
4. A background worker regenerates each affected user's timeline from the selected timestamp.
5. While a user has an active campaign work item, normal real-time timeline processing is skipped for that user to avoid overlapping timeline jobs.
6. The campaign completes when every affected user has completed or been skipped. Campaigns with failed users remain active until the failures are retried or otherwise resolved.

The selected timestamp matters. Choose the earliest point that could be affected by the bug or logic change, but avoid unnecessarily old timestamps because regenerating more history takes longer.

Create a Campaign

Navigate to Admin Dashboard > Timeline Regeneration or open:

/app/admin/timeline-regeneration-campaigns

To create a campaign:

1. Click Create Campaign.
2. Enter a unique Campaign Key. The key can be up to 120 characters and is used to identify this campaign in the Admin Panel and audit logs.
3. Select Regenerate From. Users with GPS data at or after this timestamp are eligible.
4. Enter a clear Reason. Users can see this message in the timeline refresh notification, so keep it concise and user-facing.
5. Click Run Preview to count affected users.
6. Click Review Create and verify the campaign key, timestamp, reason, and affected user count.
7. Click Create Campaign.

After creation, the campaign appears in the campaign list and starts processing automatically on the next campaign worker run.

Monitor Progress

The Timeline Regeneration page lists campaigns newest first. Use Refresh to reload the latest counters.

Column	Description
Campaign	Campaign key and reason
Source	ADMIN for campaigns created by admins, RELEASE for campaigns shipped by developers
Status	Overall campaign status
Affected From	Timestamp from which timelines are rebuilt
Progress	Processed users compared with total affected users
Failed	Number of users whose campaign work item failed
Created	Campaign creation time
Completed	Completion time, when available

Campaign statuses:

Status	Meaning
ACTIVE	The campaign still has pending, running, or failed user work items.
COMPLETED	All affected users completed or were skipped.
CANCELLED	The campaign was stopped by an internal or release-level operation. Cancelled campaigns cannot be retried from the Admin Panel.

Click View Details to inspect a campaign. The details view shows total, pending, running, completed, failed, and skipped counts. It also lists failed users with their email, name or user ID, attempt count, last error, and last update time.

Retry Failed Users

GeoPulse automatically retries campaign work items up to the configured maximum attempt count. If users remain failed after the underlying problem is fixed:

1. Open Timeline Regeneration.
2. Find the campaign with failed users.
3. Click Retry Failed Users from the list or campaign details dialog.

Only failed users are queued again. Completed users are not regenerated a second time by the retry action.

User Experience

Affected users may see a notification titled Timeline refresh scheduled. The campaign reason is used as the notification message and the notification links to the user's timeline jobs page.

No confirmation or manual action is required from the user. The background worker creates and runs the timeline regeneration job for each affected user.

Audit Logs

Admin-created campaigns and failed-user retries are recorded in Admin Dashboard > Audit Logs.

Action	When it is written
TIMELINE_REGENERATION_CAMPAIGN_CREATED	An admin creates a campaign. The audit details include the campaign key, affected timestamp, and reason.
TIMELINE_REGENERATION_CAMPAIGN_RETRIED	An admin retries failed users for a campaign.

Worker Tuning

Most installations can use the defaults. For large instances, administrators can tune the campaign worker with environment variables:

Environment Variable	Default	Description
GEOPULSE_TIMELINE_REGENERATION_CAMPAIGN_INTERVAL	5m	How often the backend checks active campaigns and queues due work.
GEOPULSE_TIMELINE_REGENERATION_CAMPAIGN_DELAY	2m	Delay after backend startup before the first campaign worker run.
GEOPULSE_TIMELINE_REGENERATION_CAMPAIGN_MAX_CONCURRENT_TASKS	2	Maximum number of campaign user jobs processed concurrently.
GEOPULSE_TIMELINE_REGENERATION_CAMPAIGN_MAX_ATTEMPTS	5	Maximum automatic attempts before a user work item remains failed.

These variables require a backend restart. The worker uses the timeline processing executor, so increasing concurrency can increase CPU, database, and geocoding load.

For the broader timeline processing settings, see Timeline Global Configuration.