A rule defines when points are awarded and how many. Every rule must have a unique rule key. The rule is the bridge between something happening in the system and the addition or deduction of points. Quite often, "something happening" is caught by a plugin. UserPoints comes with a standard set of plugins that capture things like a new user registration.
Additional plugins can be installed, and they may create and use additional rules. Any software can integrate with UserPoints through the API - calls to the API that add or deduct points require a rule key to be given.
Various options are available to define how a particular rule is applied. They are described in the sections below.
Some rules are included in the UserPoints program. You can create rules from the rule list (see below).
Rules can be automatically created by other plugins or components. The API documentation describes how to include an XML definition of a rule in a plugin or component. One or more rules can be specified in this way. When software is installed, UserPoints will scan all installed components and plugins, looking for rules, and installing any it finds. You can also trigger a scan from the control panel option Auto detect new rules.
Go to Components → UserPoints → Rules to see all rules.
The toolbar provides:
The list shows each rule's name, description, rule key, point value, publication state, and whether it is a system rule.
Rules marked as System are created automatically by the installer or auto-detection and cannot be edited. Their names, descriptions, and rule keys are fixed. You can publish or unpublish them, but to change behaviour (such as the point value) you must duplicate the rule first and work with the copy.
Each rule belongs to a category that groups it in the frontend account view:
| Code | Category |
|---|---|
| ar | Articles |
| sh | Shopping |
| us | Users |
| fo | Forums |
| sy | System |
| gm | Games |
| ot | Other |
Click New or click an existing rule's name to open the rule editor. The fields available depend on the rule key selected.
A translatable language key or plain text label displayed to users. If you use a language key (e.g. AUP_RULE_LOGIN), ensure the corresponding string exists in your language file. Plain text is displayed as-is.
A short explanation of how points are earned, shown to users in the account view and rule list.
The internal identifier that triggers this rule (e.g. up_login, up_newregistered, sysplgup_buypoints). Each installed plugin or other integration software registers one or more rule keys. When the plugin or other software fires, it looks for a published rule with a matching rule key.
This field is read-only for system rules. For custom rules it must match a rule key exactly; a mismatch means the rule never fires.
The rule key is known in the software and the database table of rules as plugin_function. But the rule key is not necessarily associated with a plugin. It may be used by any software that uses the UserPoints API to interact with the points system.
The minimum Joomla access level a user must have for this rule to fire on their behalf. Use this to restrict point awards to registered users, authors, or higher groups. The default value is Registered.
The number of points awarded (or deducted, if negative) when this rule fires. Accepts decimals.
Leave at 0 if the point amount is determined at runtime by the plugin (variable awards).
When enabled, the value in Points is always awarded regardless of any runtime value passed by the plugin. When disabled, the plugin can pass a variable point amount (for example, proportional to a purchase total). If Points is non-zero and Fixed Points is disabled, the Points value acts as a fallback default.
An optional bonus percentage applied to the award. For example, 10 means the user's referrer receives 10% of whatever the user earns under this rule.
When enabled, the user's referrer (the person who invited them) receives a bonus equal to the Percentage whenever this rule fires for the referred user.
An optional date after which the rule will no longer fire, even if it is published. Leave blank for a rule that never expires.
How long points earned by this rule remain valid before they expire. Choose Default to use the component-wide expiry setting (configured in Options), or select a specific duration from 1 day up to 10 years. This is independent of the rule expiry date: the rule expiry date controls when the rule stops firing, while the validity period controls how long each individual award of points lasts.
How often a user can earn points from this rule:
| Value | Behaviour |
|---|---|
| Once only | Each user can earn these points exactly once, ever. |
| Once per day per user | Each user can earn points once per calendar day. |
| Once per day for all users | The first user to trigger the rule each day earns points; subsequent triggers that day are ignored for everyone. |
| Whenever | Points are awarded every time the rule fires, with no frequency limit. |
| Once per week | Each user can earn points once per calendar week. |
| Once per month | Each user can earn points once per calendar month. |
| Once per year | Each user can earn points once per calendar year. |
Whether this rule is active. Unpublished rules are never triggered.
When enabled, each award from this rule appears in the user's activity history. Disable this for background housekeeping rules whose individual transactions you do not want visible to users.
When enabled, points are credited to the user immediately when the rule fires. When disabled, the activity record is created with approved = 0 and an administrator must manually approve it before the points are credited.
Use manual approval for rules where you want to review each award before it counts (for example, content submission bonuses).
When enabled, the rule fires in both directions: it awards points to the user who triggers it and credits a linked rule for the other party. This is used for peer-to-peer interactions (for example, awarding points both to a user who rates an article and to the article's author).
The display category for this rule (see the category table above).
An optional minimum point balance a user must hold before this rule can fire. Use this to create privilege-based rules that only activate once a user has accumulated enough points.
A Yes/No toggle that controls whether a notification message is shown to the user when this rule fires. When set to No, the message is suppressed even if a message text is configured below.
A short text shown to the user when they earn points from this rule. Leave blank to use the default system message.
Subject line of an email sent to the user when they earn points. Leave blank to suppress email notification for this rule.
Body text of the notification email. Supports a set of placeholders that are replaced at send time (for example, the user's name or the number of points earned).
Whether the notification email is sent as Plain Text or HTML. Choose HTML if your email body uses formatting or images.
When enabled, a copy of each notification email is sent to the site administrator.
Rules can be toggled without deleting them. An unpublished rule is invisible to users and never fires. You can batch-toggle rules using the checkboxes in the list view.
To create a variant of a system rule (for example, a rule that awards different points to users in a specific category), click the rule name to open it and then click Save as Copy. The copy will be a non-system rule you can edit freely.