# Matching rules

Refine who is matched with whom with rules based on categories, audiences and members, and understand the default rules and the matching priority.

import { Steps } from '@prosefly/astro-components';
import Callout from '@components/Callout.astro';

Matching rules optimize the composition of groups: RandomCoffee looks for the best possible combinations based on the profile of each participant. They rely on [categories](/admin/categories-and-audiences/categories/), [audiences](/admin/categories-and-audiences/audiences/) and members.

You can add matching rules with the "Cross-groups", "Group composer", "Lottery" and "Mystery 1:1s" algorithms, and in mentoring programs with the "With matching rules" matching mode. See [Matching algorithms](/admin/matching/matching-algorithms/).

<Callout type="warning">
  Matching rules are not available with the "Randomly" algorithm: the rules list does not appear. The two [default rules](#default-rules) still apply.
</Callout>

<Callout type="note">
  In mentoring programs, matching rules come with the mentoring add-on.
</Callout>

## Add a rule

<Steps>

1. **Open the matching settings of your program.**

   Open your program, go to the "Settings" tab, then to the "Matchmaking" section.

2. **Choose an algorithm that uses rules.**

   In "Matching algorithm", choose "Cross-groups", "Group composer", "Lottery" or "Mystery 1:1s". The "Matching rules" list appears below the algorithm.

3. **Click "Add a rule".**

4. **Choose the rule type** in the first list: "Category", "Category values", "Audience", "Specific members" or "Category overlap". Hover the question mark next to each type to see its description.

5. **Complete the rule**, as described for each type [below](#rule-types).

6. **Click "Save".**

</Steps>

A rule is only saved once all its fields are filled in. Next to each rule, use the copy icon ("Duplicate") to duplicate it and the bin icon ("Delete") to delete it.

## Order and priority of the rules

You can add as many rules as you want. The rules are numbered: the first one is marked "WHERE", the next ones "THEN".

**The higher a rule is in the list, the more weight it has.** RandomCoffee first tries to respect rule 1, then rule 2, and so on. Drag a rule by its handle ("Drag to reorder") to change its rank.

Rules are optimizations, not guarantees: when all rules cannot be respected for everyone, the lower rules give way first. To only keep the groups that respect your rules, see [Matching priority](#matching-priority).

### Example of a rules list

| Rank | Rule | What it does |
| --- | --- | --- |
| WHERE 1 | "People who have already met should not meet again, as far as possible" | Default rule: avoids repeat matches. |
| THEN 2 | "Match members according to their selected matching preferences" | Default rule: takes members' preferences into account. |
| THEN 3 | "Category" "Department" "Is different" | Favors matches between departments. |
| THEN 4 | "Category" "Time zone" "Is the closest" | Favors matches between close time zones. |
| THEN 5 | "Category values" "Corporate Communication" "Must not be matched with" "R&D" | Keeps these two departments apart. |
| THEN 6 | "Audience" "Newcomers" "Must be matched with" "Mentors who have not been matched yet" | Matches each newcomer with one of these mentors. |
| THEN 7 | "Specific members" [a manager] "Must not be matched with" [two members of their team] | Avoids a precise match. |

## Default rules

Every program that uses matching rules starts with two default rules. You cannot delete them, but you can drag them to change their rank among your rules.

### "People who have already met should not meet again, as far as possible"

RandomCoffee looks at all the past matches of your workspace, in every program, and favors people who have never been matched together.

- When a repeat cannot be avoided, RandomCoffee prefers the people who were matched together the longest time ago.
- So people can meet again: the rule lowers the chances, it does not forbid it.
- With the "Optimize matching quality" priority, the rule becomes strict (see [Matching priority](#matching-priority)): people who have already been matched together are not matched again, unless one of them has already met everyone else in the session. In that case, the oldest half of their past matches become possible again.

### "Match members according to their selected matching preferences"

Members can state the profiles they want to meet or avoid, and rank their preferences, from "My Preferences" in their [Member Portal](/members/getting-started/member-portal/). This rule favors the partners who fit these preferences. See [Set matching preferences](/members/profile-and-preferences/matching-preferences/).

<Callout type="note">
  At the lowest priority, after all your rules, RandomCoffee also favors variety: it prefers partners whose categories differ from those of the people each member has met before. This rule does not appear in the list.
</Callout>

## Rule types

### Category

Compares the values of two members for one category: for example, match people from different departments, or with the closest hiring dates. Choose the category, then the comparison. The comparisons available depend on the category type:

| Category type | Comparisons | Example |
| --- | --- | --- |
| Dropdown | "Is the same", "Is different", "Is the closest", "Is the furthest" | "Department" "Is different" |
| Multiple Choice | "Has the most in common", "Has the least in common" | "Skills" "Has the most in common" |
| Date | "Is the closest", "Is the furthest" | "Hiring date" "Is the closest" |
| Number | "Is the closest", "Is the furthest" | "Time zone" "Is the closest" |
| Short Text | "Has the most in common", "Has the least in common" | "Hobby" "Has the most in common" |
| Yes/No | "Is the same", "Is different" | "Internal mobility project?" "Is the same" |

- "Is the same" and "Is different" sort members into two groups: those who meet the condition and those who do not.
- The other comparisons are gradual: RandomCoffee favors the closest (or furthest) values, or the most (or fewest) values in common.
- For a Dropdown category, "Is the closest" and "Is the furthest" compare values that look like time zones as time offsets, plain numbers as numbers, and other values by text similarity. See [Manage time zone differences](/admin/matching/time-zones/).
- Members without a value for the category are treated as not meeting the rule. Fill in the category for everyone in the program.

See [Categories](/admin/categories-and-audiences/categories/) for the six category types.

### Category values

Forces or prevents matches between members with specific category values, within the same category or across categories.

1. In the first field, select one or more values.
2. Choose "Must be matched with" or "Must not be matched with".
3. In the last field, select one or more values.

Only Dropdown and Multiple Choice categories can be used here: Short Text, Date, Number and Yes/No categories do not have values to select.

| First values | Logic | Last values | Result |
| --- | --- | --- | --- |
| "IT" | "Must not be matched with" | "R&D", "Operations" | Members of IT are not matched with members of R&D or Operations. |
| `GMT+10:00 (Australian Eastern Standard Time)`, `GMT-08:00 (Pacific Standard Time)` | "Must be matched with" | `GMT+14:00 (Line Islands Time)` | Members in the first two time zones are matched with members in the third one. |

The rule works both ways, and only concerns the members who have one of the selected values. With "Must be matched with", members with the first values are matched with members with the last values (and the other way around), rather than with anyone else. Members who have none of these values are not affected.

### Audience

Forces or prevents matches between the members of selected [audiences](/admin/categories-and-audiences/audiences/), static or dynamic. Useful to connect program cohorts or groups.

1. In the first field, select one or more audiences.
2. Choose "Must be matched with" or "Must not be matched with".
3. In the last field, select one or more audiences.

Example: "Newcomers" "Must be matched with" "Mentors who have not been matched yet". Like "Category values", the rule works both ways and does not affect members who are in none of the selected audiences.

### Specific members

Forces or prevents matches between named members, when you need a precise exception: for example, so that a manager is not matched with the members of their own team.

1. In the first field, search for and select one or more members.
2. Choose "Must be matched with" or "Must not be matched with".
3. In the last field, select one or more members.

### Category overlap

Compares two Multiple Choice categories that share the same options, such as mentor skills and mentee skills. Choose a "Source category", then "Maximize overlap" or "Minimize overlap", then a "Target category". The target list only shows the Multiple Choice categories that share at least one option with the source category.

This rule is mostly used in mentoring programs: see [Skill-based matching](/admin/mentoring/create-a-mentoring-program/#skill-based-matching).

## Matching priority

The "Matching priority" setting decides what happens to the groups that do not fully respect your rules. It has two options:

- **"Optimize people participation"** (default): RandomCoffee generates the best possible matches for everyone, even if some rules are not perfectly met.
- **"Optimize matching quality"**: RandomCoffee only keeps the groups that perfectly fit your rules. Some people may stay unmatched.

The setting appears in mentoring programs that use the "With matching rules" matching mode. When it is not shown, your program uses "Optimize people participation".

With "Optimize matching quality", the strict rules are:

- "Category" rules with "Is the same" or "Is different";
- "Category values", "Audience" and "Specific members" rules;
- the two default rules.

A group that breaks one of them for any of its members is removed. The gradual comparisons ("Is the closest", "Is the furthest", "Has the most in common", "Has the least in common") and "Category overlap" rules never remove a group.

<Callout type="note">
  "Optimize matching quality" is designed for the "Group composer" algorithm and for mentoring programs, where it removes the groups that break a strict rule. With "Cross-groups", "Lottery" and "Mystery 1:1s", groups are generated as with "Optimize people participation". See [Group composer](/admin/matching/group-composer/#matching-rules-and-priority).
</Callout>