Mission Domain

The mission system turns user actions into structured goals. It answers questions like "Has this user completed 10 quizzes this week?" or "Has the marketing team collectively finished 50 activities this month?"

This section covers the full configuration model: entity hierarchies, matching logic, assignment modes, and lifecycle management. It is relevant for anyone configuring missions through the dashboard or integrating them via API. For a high-level overview of what missions do, see the Gamification Fundamentals. For shared patterns used across all domains (JsonLogic expressions, timeframes, entity matching), see Cross-Cutting Patterns.

The domain is built around four entities that form a clear hierarchy:

MissionConfiguration  (what counts and how to count it)
      │
      └──▶ MissionRule  (when, for whom, and how to assign)
                │
                └──▶ Mission  (per-user or per-group tracking instance)
                        │
                        └──▶ MissionLog  (immutable progress audit trail)

Mission Configuration

A Mission Configuration defines what user actions count toward a mission and how progress is measured. It is the template that specifies matching logic, increment rules, and completion targets.

Fields

Field	Type	Description
`missionConfigurationId`	nanoid	Unique identifier
`name`	string	Human-readable reference (e.g., "Answer 10 Quizzes Correctly")
`missionType`	`INDIVIDUAL` \| `GROUP`	Whether missions track one user or a group
`matchType`	`INSTANCE` \| `ENTITY` \| `TAG`	How to match incoming events
`matchEntity`	`Activity` \| `Quiz` \| `Tag`	Which entity type to watch
`matchEntityId`	string?	Specific entity or tag ID (required for `INSTANCE` and `TAG`)
`matchCondition`	JsonLogic	Additional matching logic evaluated at runtime
`incrementExpression`	JsonLogic	How much progress each matching event adds
`targetAmountExpression`	JsonLogic	The completion threshold
`origin`	`CATALOG` \| `CUSTOM`	Where this configuration was created
`defaultLang`	lang	Default language code
`langs`	lang[]	Supported languages (1–10)

Match Types

INSTANCE: Matches a specific entity. Example: completing activity abc123. Requires matchEntityId.

ENTITY: Matches any entity of that type. Example: completing any quiz.

TAG: Matches any entity tagged with the given tag. Example: completing any activity tagged sustainability. Requires matchEntityId (the tag ID).

Expressions

The three expression fields are what make mission configurations flexible:

matchCondition filters which events qualify. It receives { mission } as context and must return a truthy value for the event to count. Example: only count quizzes with outcome SUCCESS.

incrementExpression defines how much progress each qualifying event adds. It receives { user, event } and must return a number. A static value like 1 means "add 1 per event". A conditional expression can award different amounts based on context — for instance, awarding 2 for hard quizzes and 1 for easy ones.

targetAmountExpression defines when the mission is complete. It receives { user, mission } and must return a number. A static 10 means "complete after 10 increments". A dynamic expression can set different targets per user — for instance, a higher target for premium users.

Constraint: When a JsonLogic expression evaluates to null, empty string, or NaN, the system defaults to 1 for both increment and target calculations.

Mission Rule

A Mission Rule defines when and for whom missions are assigned. Every rule references one or more Mission Configurations (via a pool or matching condition) and controls how those configurations are instantiated as actual missions for users.

Core Fields

Field	Type	Description
`missionRuleId`	nanoid	Unique identifier
`name`	string	Human-readable name
`missionType`	`INDIVIDUAL` \| `GROUP`	Must match the referenced configurations
`state`	`PENDING` \| `ACTIVE` \| `ENDED`	Lifecycle state
`assignmentMode`	`LAZY` \| `EVENT` \| `DISABLED`	How missions are assigned to users
`usersMatchCondition`	JsonLogic?	Which users this rule applies to (required for INDIVIDUAL)
`missionsMatchCondition`	JsonLogic	Filters which configurations to instantiate
`missionConfigurationsPool`	string[]?	Explicit list of configuration IDs to use (alternative to matching)

Assignment Modes

The assignment mode determines how and when missions are created for users:

LAZY: Missions are created on-demand when a user browses available missions. If the user matches the rule's conditions, the mission is generated in real time. Ideal for discovery-driven experiences where users choose which missions to pursue.

EVENT: Missions are assigned automatically when a matching event occurs — for example, assigning a follow-up mission when the user completes a Learning Path. This is real-time and reactive.

DISABLED: No assignments are made. Used for deactivating a rule without deleting it.

Event Mode Fields

When assignmentMode is EVENT, four additional fields become required:

Field	Type	Description
`eventMatchType`	`INSTANCE` \| `ENTITY` \| `TAG`	How to match the triggering event
`eventMatchEntity`	`Activity` \| `Quiz` \| `Tag` \| `User`	Which entity type triggers assignment
`eventMatchEntityId`	string	Specific entity or tag ID
`eventMatchCondition`	JsonLogic	Additional filtering on the event

Constraint: All four eventMatch* fields are required when assignmentMode is EVENT and must be absent for other modes.

User and Mission Targeting

usersMatchCondition determines which users are eligible for this rule. It receives { user, activeMissions } as context — where activeMissions is the list of missions already assigned to the user. This allows rules like "only assign if the user doesn't already have 3 active missions".

Constraint: usersMatchCondition is required for INDIVIDUAL rules and must be absent for GROUP rules (the entire group is eligible by definition).

missionsMatchCondition filters which Mission Configurations should be instantiated. It receives { user, activeMissions, mission } where mission is a candidate configuration. This allows rules like "only assign configurations tagged with the user's department".

missionConfigurationsPool is an alternative to missionsMatchCondition — an explicit list of configuration IDs. When present, only these configurations are considered.

Timeframe

Field	Type	Description
`timeframeType`	`PERMANENT` \| `RANGE` \| `RECURRING`	Whether the rule runs indefinitely, once, or repeats
`timeframeStartsAt`	ISO datetime	When the rule begins
`timeframeEndsAt`	ISO datetime?	When the rule ends (required for `RANGE` and `RECURRING`)
`timeframeTimezoneType`	`FIXED` \| `USER`	Whether to use a fixed timezone or each user's own
`timeframeTimezone`	timezone?	The fixed timezone (required when `FIXED`)
`recurrence`	`DAILY` \| `WEEKLY` \| `MONTHLY` \| `CUSTOM`?	Reset cadence (required for `RECURRING`)
`scheduleCron`	cron?	Cron expression (required when recurrence is `CUSTOM`)

For a full explanation of timeframe, recurrence, and timezone handling, see the Cross-Cutting Patterns document.

Group Targeting

Field	Type	Description
`groupTagId`	string?	The tag that identifies the group (required for `GROUP` rules)

Constraint: GROUP rules require groupTagId. INDIVIDUAL rules must not have it.

Mission (Assignment)

A Mission is a tracking instance — the concrete assignment of a Mission Configuration to a specific user or group under a specific rule. It holds the current progress and the frozen target.

Fields

Field	Type	Description
`missionId`	nanoid	Unique identifier
`missionConfigurationId`	nanoid	The configuration this mission is based on
`missionRuleId`	nanoid?	The rule that triggered this assignment
`missionType`	`INDIVIDUAL` \| `GROUP`	Inherited from configuration
`userId`	nanoid?	The user this mission belongs to (INDIVIDUAL only)
`groupTagId`	string?	The group this mission belongs to (GROUP only)
`state`	`PENDING` \| `ACTIVE` \| `ENDED`	Lifecycle state
`isCompleted`	boolean?	Whether the target has been reached
`completedAt`	ISO datetime?	When the mission was completed
`currentAmount`	number	Accumulated progress
`targetAmount`	number	Frozen completion threshold
`periodId`	string	Deduplication key for recurring missions

The mission also carries copies of matching and expression fields from the configuration (matchType, matchEntity, matchEntityId, matchCondition, incrementExpression, targetAmountExpression) so that progress tracking does not depend on the configuration remaining unchanged.

Mission Types

INDIVIDUAL missions are assigned to a single user. Each user gets their own mission instance with independent progress tracking. When currentAmount >= targetAmount, the mission is marked as completed and stops accepting further increments.

GROUP missions are assigned to a group identified by a tag. All users in the group contribute to the same currentAmount. Unlike individual missions, group missions continue counting after reaching the target — they track cumulative group progress without capping.

Constraint: INDIVIDUAL missions require userId and forbid groupTagId. GROUP missions require groupTagId and forbid userId.

Period Identification

The periodId field serves as a deduplication key that prevents the same rule from assigning duplicate missions in the same time period:

Timeframe	periodId Format	Example
`PERMANENT`	`"PERMANENT"`	`PERMANENT`
`RANGE`	Rule's start time in UTC	`2025-01-01T00:00:00`
`RECURRING` / `DAILY`	`YYYY-MM-DD`	`2025-09-15`
`RECURRING` / `WEEKLY`	`YYYY-Www`	`2025-W38`
`RECURRING` / `MONTHLY`	`YYYY-MM`	`2025-09`
`RECURRING` / `CUSTOM`	Cron last-fire time in UTC	`2025-09-15T06:00:00`

A MissionRuleEvaluation record is created each time a rule is evaluated for a user/group in a given period, preventing duplicate assignments.

Status Lifecycle

    rule assigns mission
           │
    ┌──────▼──────┐
    │   PENDING    │ ◀── mission starts in the future
    └──────┬──────┘
           │  startsAt reached
           ▼
    ┌─────────────┐     currentAmount >= targetAmount
    │   ACTIVE    │ ──────────────────────────────────▶ isCompleted = true
    └──────┬──────┘     (INDIVIDUAL only; GROUP keeps counting)
           │  endsAt reached
           ▼
    ┌─────────────┐
    │   ENDED     │ ◀── timeframe expired
    └─────────────┘

PENDING: The mission exists but its timeframe hasn't started. targetAmount is not yet calculated.

ACTIVE: The mission is accepting progress. On transition to ACTIVE, the targetAmount is calculated from targetAmountExpression and frozen — subsequent changes to the expression or user context do not affect it.

ENDED: The timeframe has expired. Terminal state.

Mission Log

A Mission Log is an immutable record created every time a mission's progress is updated. It provides a complete audit trail of which user contributed what amount and when.

Fields

Field	Type	Description
`missionLogId`	nanoid	Unique identifier
`missionId`	nanoid	The mission that was updated
`missionConfigurationId`	nanoid	The configuration reference
`missionType`	`INDIVIDUAL` \| `GROUP`	Mission type
`userId`	nanoid	The user who triggered the progress
`groupTagId`	nanoid?	For group missions
`amount`	number	The increment applied (default: 1)
`additionalData`	record?	Extra context from the source event

For group missions, the userId records which user in the group contributed, while the increment applies to the shared currentAmount.

How Missions Are Assigned

When a user action occurs (completing an activity, passing a quiz, etc.), the system follows different paths depending on the assignment mode:

EVENT Mode Flow

The source system (Activity, Quiz, etc.) publishes an event.

The mission engine queries for all ACTIVE rules with assignmentMode: EVENT that match the event's entity type and ID.

For each matching rule:

The eventMatchCondition is evaluated against the event data.

The usersMatchCondition is evaluated against the user (for INDIVIDUAL) or skipped (for GROUP).

The missionsMatchCondition (or missionConfigurationsPool) determines which configurations to instantiate.

A MissionRuleEvaluation check prevents duplicate assignments in the same period.

New Mission assignments are created in batch.

LAZY Mode Flow

A user browses available missions (e.g., opens the missions screen).

The system queries for all ACTIVE rules with assignmentMode: LAZY.

For each rule, the same evaluation chain runs: user eligibility → configuration matching → deduplication check.

Eligible missions are created on-the-fly and returned to the user.

Source Event Remapping

Source events are remapped to match entity types before evaluation:

Source Event	Maps To
`ActivityLog`	`Activity`
`QuizLog`	`Quiz`
Others	Pass through

How Progress Is Tracked

When a user performs an action that might count toward a mission:

The system queries for all ACTIVE, non-completed missions that match the event (by matchType, matchEntity, matchEntityId).

For each matching mission, the matchCondition is evaluated against the event context.

If the condition passes, the incrementExpression is evaluated to determine how much to add.

The mission's currentAmount is atomically incremented.

An immutable MissionLog entry is created.

For INDIVIDUAL missions: if currentAmount >= targetAmount, the mission is marked as completed (isCompleted: true, completedAt set).

For GROUP missions: the counter continues regardless of whether the target was reached.

Idempotency

The counter update is idempotent — if the same event is processed twice (due to retries or at-least-once delivery), the mission's currentAmount is only incremented once. This is enforced via an idempotency key based on the event ID.

Mission completion uses a conditional database update that only sets isCompleted: true if it was previously false, preventing double-completion.

Example: Full Configuration

Consider a company that wants to create a weekly quiz challenge: "Complete 5 quizzes with a passing score each week."

Step 1: Mission Configuration

{
  "missionConfigurationId": "mc_quiz_weekly",
  "name": "Weekly Quiz Challenge",
  "missionType": "INDIVIDUAL",
  "matchType": "ENTITY",
  "matchEntity": "Quiz",
  "matchCondition": { "===": [{ "var": "event.outcome" }, "SUCCESS"] },
  "incrementExpression": 1,
  "targetAmountExpression": 5,
  "defaultLang": "en",
  "langs": ["en", "it"]
}

This says: count any quiz completion where the outcome is SUCCESS, add 1 per event, complete at 5.

Step 2: Mission Rule

{
  "missionRuleId": "mr_quiz_weekly",
  "name": "Weekly Quiz Rule",
  "missionType": "INDIVIDUAL",
  "assignmentMode": "LAZY",
  "usersMatchCondition": true,
  "missionsMatchCondition": true,
  "missionConfigurationsPool": ["mc_quiz_weekly"],
  "timeframeType": "RECURRING",
  "timeframeStartsAt": "2025-01-06T00:00:00Z",
  "timeframeEndsAt": "2025-12-31T23:59:59Z",
  "timeframeTimezoneType": "USER",
  "recurrence": "WEEKLY",
  "defaultLang": "en",
  "langs": ["en"]
}

This says: every week, make this mission available to all users (LAZY — they see it when they browse missions). Use each user's local timezone for week boundaries.

Step 3: What Happens at Runtime

Monday: User opens the missions screen. The LAZY rule is evaluated. A new Mission is created:

periodId: "2025-W38", state: "ACTIVE", currentAmount: 0, targetAmount: 5

Tuesday: User completes a quiz with outcome SUCCESS. The matchCondition passes. incrementExpression returns 1. Mission becomes currentAmount: 1.

Wednesday: User completes a quiz but fails. The matchCondition evaluates to false (outcome is not SUCCESS). No increment.

Friday: User completes 4 more passing quizzes. Mission reaches currentAmount: 5, isCompleted: true.

Next Monday: A new period begins (2025-W39). The LAZY rule creates a fresh mission with currentAmount: 0.

Alternative: Event-Based Team Mission

{
  "missionRuleId": "mr_team_event",
  "name": "Team Onboarding Challenge",
  "missionType": "GROUP",
  "groupTagId": "department:engineering",
  "assignmentMode": "EVENT",
  "eventMatchType": "ENTITY",
  "eventMatchEntity": "Activity",
  "eventMatchEntityId": "activity_onboarding",
  "eventMatchCondition": true,
  "missionsMatchCondition": true,
  "missionConfigurationsPool": ["mc_team_onboarding"],
  "timeframeType": "RANGE",
  "timeframeStartsAt": "2025-09-01T00:00:00Z",
  "timeframeEndsAt": "2025-09-30T23:59:59Z",
  "timeframeTimezoneType": "FIXED",
  "timeframeTimezone": "Europe/Rome"
}

This says: when any user completes the onboarding activity, assign a group mission to the engineering department. The mission tracks collective progress from September 1–30, Rome time.

Summary of Key Concepts

Concept	Purpose
MissionConfiguration	Defines what events count and how to measure progress (matching + expressions)
MissionRule	Defines when, for whom, and how missions are assigned (timeframe + targeting + mode)
Mission	Per-user or per-group tracking instance with frozen target and live progress
MissionLog	Immutable audit trail of every progress event
assignmentMode	How missions are created: `LAZY` (on-demand), `EVENT` (reactive), `DISABLED` (off)
missionType	`INDIVIDUAL` (one user, stops at target) or `GROUP` (shared counter, keeps going)
matchType	How events are matched: `INSTANCE` (specific), `ENTITY` (any of type), `TAG` (by tag)
periodId	Deduplication key ensuring one mission per rule per time period
targetAmount	Frozen when mission becomes ACTIVE — immune to later configuration changes
MissionRuleEvaluation	Tracks which rule+period combinations have been evaluated, preventing duplicates

Reward and Currency Domain: mission completion events can trigger reward rules, automatically awarding virtual currency.

Leaderboard Domain: leaderboards can rank users by mission-related metrics.

Streak Domain: streaks can track activity completions that also feed into missions.

Cross-Cutting Patterns: JsonLogic expressions, entity matching, timeframe and scheduling, and state lifecycle patterns used throughout this domain.

Mission Configuration#

Fields#

Match Types#

Expressions#

Mission Rule#

Core Fields#

Assignment Modes#

Event Mode Fields#

User and Mission Targeting#

Timeframe#

Group Targeting#

Mission (Assignment)#

Fields#

Mission Types#

Period Identification#

Status Lifecycle#

Mission Log#

Fields#

How Missions Are Assigned#

EVENT Mode Flow#

LAZY Mode Flow#

Source Event Remapping#

How Progress Is Tracked#

Idempotency#

Example: Full Configuration#

Step 1: Mission Configuration#

Step 2: Mission Rule#

Step 3: What Happens at Runtime#

Alternative: Event-Based Team Mission#

Summary of Key Concepts#

Related Domains#

Mission Configuration

Fields

Match Types

Expressions

Mission Rule

Core Fields

Assignment Modes

Event Mode Fields

User and Mission Targeting

Timeframe

Group Targeting

Mission (Assignment)

Fields

Mission Types

Period Identification

Status Lifecycle

Mission Log

Fields

How Missions Are Assigned

EVENT Mode Flow

LAZY Mode Flow

Source Event Remapping

How Progress Is Tracked

Idempotency

Example: Full Configuration

Step 1: Mission Configuration

Step 2: Mission Rule

Step 3: What Happens at Runtime

Alternative: Event-Based Team Mission

Summary of Key Concepts

Related Domains