Missions

Main flow

Missions connect group enrollment, time windows, tasks, skills, and milestone availability into one progression flow.

The flow is:

1. A user is a member of one or more groups.
2. A mission enrollment links a mission to groups and waves.
3. The user may be enrolled by default, required to join, or allowed to opt in.
4. Enrolled missions expose milestones (potentially, based on milestone gateway rules) to the user.
5. Active milestones give the user access to tasks.
6. Completed activities are checked against task rules.
7. Matching task rules create task contributions.
8. Task contributions update member and group skill achievements.
9. Milestone gateway rules use those achievements to decide which milestones are active.

When a mission is visible

A mission can be shown to a participant when all base rules match:

1. The mission is published.
2. The participant is a member of a group that is linked to the mission enrollment.
3. The linked wave is active now, or has no start and end date.
4. The participant is effectively enrolled, or can choose to enroll.

A wave is active when one of these rules matches:

1. It has no start and no end date.
2. Its start date is in the past and its end date is in the future or empty.
3. Its end date is in the future and its start date is in the past or empty.

The participant missions page shows two lists:

1. My missions: missions with an active milestone and an effective enrollment.
2. Available missions: missions that have not been active for the user yet and where the user is not effectively enrolled.

A mission can also be used by other views when it has an active milestone enrollment for the user.

Joining and leaving a mission

Mission enrollment is set at group level. The group status can be:

1. required: the user must take part.
2. optedIn: the user takes part by default.
3. optedOut: the user does not take part by default.

A participant can save a personal decision for each membership:

1. optedIn: join the mission.
2. optedOut: leave the mission.

The effective result is:

1. required always enrolls the user. The user cannot opt out.
2. optedIn enrolls the user unless they chose optedOut.
3. optedOut does not enroll the user unless they chose optedIn.

If a user belongs to more than one linked group, the page may show a mixed state. If any linked group requires the mission, the enrollment controls are disabled.

Changing the choice calls the mission enrollment API and then refreshes the page data.

How milestones start and stop

A milestone is active for a user through a milestoneEnrollment record. It has a start time and may have an end time.

The system can create missing milestone enrollments when a user has an effective mission enrollment. This first applies to initial milestones. Later, task progress can open more milestones.

A milestone is active when:

1. Its start time is in the past.
2. Its end time is in the future or empty.
3. The mission wave is active.
4. The user is still effectively enrolled in the mission.

A milestone is treated as past work when its enrollment has ended.

How tasks create progress

When a user completes an activity, the system looks for tasks that can receive that activity as input.

A task can receive the activity when:

1. The task uses the same activity template.
2. The task is in a currently active milestone for the user.
3. The task mission is published.
4. The mission wave is active.
5. The user is effectively enrolled through a participant membership.

Each matching task has one or more task rules. The system evaluates the task rules against the activity properties. The first matching rule wins.

If a rule matches, the system evaluates its skill outcome expressions. Each outcome returns completion percentage points for a skill. For each non-zero score, the system creates a taskContribution.

A task contribution stores:

1. The member skill achievement it updates.
2. The task.
3. The activity.
4. The awarded completion percentage points.

After that, the system updates skill totals.

Member and group skill achievements

A memberSkillAchievement stores one member's progress for one skill. Its completionPercentage is the sum of that member's task contributions for that skill, capped at 100.

A groupSkillAchievement stores group stats for one skill. It is recalculated from all enrolled participant members in the group and mission. It stores:

1. sum: total member progress.
2. min: lowest member progress.
3. max: highest member progress.
4. avg: average member progress.
5. median: median member progress.
6. countOfContributors: members with progress above 0.

These values can be used by milestone availability rules. This lets a milestone depend on personal progress, group progress, or both.

Expression language

Task and milestone rules use the ZEN expression language from GoRules.

There are two main modes:

1. Decision table input rules use unary tests.
2. Expression nodes use full expressions.

Unary tests are short checks against the current input. Examples:

> 50
>= 80 and <= 100
"approved", "accepted"

Full expressions return a value. Examples:

score * 10
passed ? 100 : 0
mathSkill.achievements.member.completionPercentage >= 80 ? 100 : 0

Expressions can use numbers, strings, booleans, arrays, objects, comparisons, and, or, not, ternary logic, and null coalescing with ??.

Task compliance expressions

A task rule has a complianceExpression. The system builds a decision table from all rules for the task.

The input is the activity properties. The decision table checks each rule in order and uses the first match.

If no rule matches, no contribution is created.

Example intent:

score >= 7 and status == "passed"

This means the rule matches only when the activity has a high enough score and a passed status.

Completion percentage expressions

After a task rule matches, each linked skill has a completionPercentageExpression.

The input is still the activity properties. The result is the number of completion percentage points to add for that skill.

Example intent:

score >= 9 ? 25 : 10

This awards 25 points for a high score and 10 points otherwise.

Only non-zero results create task contributions. Member skill progress is capped at 100 after all contributions are summed.

Milestone availability expressions

A milestone can have one or more gateways. Each gateway has an availabilityExpression.

The system builds a decision table from the milestone gateways. If a gateway expression matches, the milestone is available.

Gateway expressions receive two kinds of input.

Skill achievement input is keyed by skill href:

skillHref.achievements.member.completionPercentage
skillHref.achievements.group.sum
skillHref.achievements.group.min
skillHref.achievements.group.max
skillHref.achievements.group.avg
skillHref.achievements.group.median
skillHref.achievements.group.countOfContributors
skillHref.achievements.group.countOfParticipants

Enrollment count input is available at:

enrollments.count.total.member
enrollments.count.active.member

Example intent:

writing.achievements.member.completionPercentage >= 80

This opens the milestone when the member has at least 80 percent progress on the writing skill.

Another example:

enrollments.count.active.member == 0 and teamwork.achievements.group.avg >= 60

This opens the milestone when the member has no active milestone in the mission and the group average for teamwork is at least 60.

How availability changes over time

Availability is checked in two places:

1. When pending milestone enrollments are created.
2. After task contributions update skill achievements.

If an active milestone is no longer available, its open enrollment is ended.

If a not-yet-active milestone becomes available, the system creates open milestone enrollments for the whole team in that group.

If a gateway expression fails during initial enrollment, the milestone is not opened. If an active milestone gateway fails during end checks, the system may keep the milestone open rather than close it by mistake.

Progress shown in the app

Mission and milestone status can include average completion percentages.

For skills, the app reads member skill progress and shows a progress bar.

For milestones, a progressExpression can calculate an averageCompletionPercentage from the same skill achievement input used by availability rules. The result is clamped between 0 and 100.

If a milestone has no progress expression, progress defaults to 0 or is not shown, depending on the view.