Projects are composed of Subjects which are made of Skills (or Skill Groups) and a single skill defines a training unit within the gamification framework. To complete a skill, users may need to perform the same action multiple times - repetition is important for retention after all. A Skill definition specifies how many times a skill has to be performed. Each occurrence is called a Skill Event.
To create a skill, navigate to
Project -> Subject then click on
Skill +, the following skill properties can be specified:
|Skill Name||Display name of the skill|
|Skill ID||Skill ID that will be used to report skill events|
|Point Increment||Number of points added for each skill event; used in conjunction with the 'Occurrences to Completion' property|
|Occurrences to Completion||Number of successful occurrences to fully accomplish this skill; used in conjunction with the 'Point Increment' property|
|Time Window||Used in conjunction with the 'Max Occurrences Within Window' property; once this Max Occurrences is reached, points will not be incremented until outside of the configured Time Window. When 'Time Window' is disabled skill events are applied immediately."|
|Max Occurrences Within Window||Used in conjunction with the Time Window property; Once this Max Occurrences is reached, points will not be incremented until outside of the configured Time Window.|
|Self Reporting||(Optional) When checked Self Reporting is enabled for this skill. The type of |
|Version||(Optional) Utilize Skills Versioning to support running multiple versions of client software|
|Description||(Optional) Description of how to perform this skill. The Description property supports markdown.|
|Help URL/Path||(Optional) URL pointing to a help article providing further information about this skill or capability. Please note that this property works in conjunction with the Root Help Url project setting|
To calculate the total points that completion of a particular skill will give a user:
Total Points = Point Increment * Occurrences to Completion
# Copy Skill
To use an existing Skill as a template for a new Skill, you can use the button available on a Skill row displayed on the Subject page.
This will open a new Skill dialog populated with the details of the selected copy-from Skill. The name and id will be prepended with
Copy of which can be changed
before the new Skill is saved. Saving this dialog will create a new Skill that falls within the same Subject as the copy-from Skill.
# Best Practices
- "Repetition is the mother of learning" - use the
Occurrences to Completionproperty in conjunction with the Time Window property to balance between requiring repetition of an action and spacing out that repetition (for example, prevent users from spamming an action in one sitting to max out a Skill by setting a Time Window of 1-8 hours)
- Help Url - configure the Root Help Url for the project and then enter a path relative to that root. It will then be an easy change if the location of help articles changes.
# Time Window
Time Window is a powerful feature that limits awarding of points to a maximum number of occurrences within the configured time span. This feature provides a balance between requiring repetition of an action and spacing out that repetition.
“Repetition is the mother of learning, the father of action, which makes it the architect of accomplishment.” - Zig Ziglar
When designing a gamification profile, the Time Window must be considered in conjunction with the
Occurrences to Completion property.
For example, you may want to require 30 occurrences to complete a skill but only up to 5 occurrences within a 24 hour window.
This means that it will take a user at a minimum, 6 days to complete this skill. Here are the properties for this hypothetical example:
- Occurrences to Completion: 30
- Time Window: 24 hours 0 minutes
- Max Occurrences Within Window: 5
This is just a fictitious example and values will depend on your gamification needs.
You can also disable the Time Window property of a Skill, which will force each event to be applied immediately (up to
Occurrences to Completion). To disable, uncheck the checkbox next to the Time Window property.
# Skills Versioning
Skill versioning is a mechanism that allows the addition of new skills without affecting existing software running with an older skill profile. Versioning is mostly pertinent to the Display Libraries that visualize the skill profile for the version they were declared with.
Here are simple steps to enable Skills Versioning in your application:
- When creating a skill, specify a target version (always last deployed version + 1)
- Version selection can be found on the top-right in the create/edit skills dialogued
- When initializing the display component, provide the latest target version for that instance.
Let's walk through a simple scenario to get a better understanding of how Skill Versioning operates.
We have developed software and are releasing a
version 0 that integrates skills display and event reporting using the Vue.js library.
In the initial release, all of the skills will be created with
version 0. The integrated display component will then be initialized with
This software instance will then get deployed and the skill profile for
version 0 is displayed.
Now we are working on the next release which we will label as
Any skill created with
version 1 will not be visible in the already deployed software, configured to visualize skills with
The version will need to be updated in the integrated display component to use
version 1, like this:
The updated software running the
version 1 profile will expose skills declared with both
version 0 and
Both versions of software can then run simultaneously and each version will present its own gamification profile.
The skills from previous versions are automatically included, so version 3 will contain skills declared with versions 3, 2, 1 and 0
Conveniently, the Skills Dashboard provides a way to view the Client Display for a specific version.
Project -> User -> Client Display and then select a previous version on the drop-down located above the client display.
- Deletes are not directly supported. To remove a skill, please perform the following procedure:
- update all the client code that is reporting events for the skill that is to be deleted
- deploy the version that is not using the skill
- delete the skill using the dashboard
- Edits to skills are not versioned and will be immediately visible to any display with this or earlier versions. This is mostly likely the behavior you want as any edit to a skill is a fix or an improvement.
- Versioning is only applicable to new skills and doesn't apply to operations done on subjects, badges or other items within the gamificiation framework.
# Manually Add Skill Event
In the event that a Skill is not automatically reported (Skills such as "Attend Presentation" or "Submit a Success Story" are examples of Skill events that might require manual addition), Skill Events can be manually added through the Dashboard.
- Locate the Subject that contains the Skill for which you would like to add an event
Managefor the located Subject
- Locate the Skill and select
Filterbox on the top left of the Skills table can be used to quickly locate a particular Skill
Add Eventfrom the Navigation menu on the left
- Enter the
User Idof the user for whom the Skill Event will be added (note that the field supports type-ahead to locate existing users)
- Enter a date on which the Skill Event occurred (this will default to today's date)
# Incremental Changes
This section explain how various scenarios are handled when skills are modified/removed/added AFTER your application users already earned points, completed skills, achieved levels and obtained badges.
- Never take away achieved levels and/or earned badges.
- Re-calculate users' points when skill's points and/or occurrences are mutated.
SCENARIO: Point Increment is increased ⬆️
Recall that Point Increment is the number of points applied for each skill event. Delta in Point Increment will then be added for any of the already performed skill events. For example if a user performed 2 skill events and Point Increment changed from 5 points to 8 points (delta = 3) then user will be awarded additional 6 (3 * 2) points. If these additional points place a user into the next level then that level will be awarded the next time an event is reported for that user.
SCENARIO: Point Increment is increased ⬇️
Recall that Point Increment is the number of points applied for each skill event. Delta in Point Increment will then be substructed for any of the already performed skill events. For example if a user performed 2 skill events and Point Increment changed from 10 points to 6 points (delta = 4) then 8 (4 * 2) points will be substructed from the user's points.
SCENARIO: Occurrences to Completion is increased ⬆️
Recall that Occurrences to Completion is the number of successful occurrences to fully accomplish a skill. Any users that have already completed the skill based on the lower number of occurrences will now have an opportunity to complete new/additional occurrences and earn those points.
Additional occurrences will cause a completed skill to be worth additional points which in turn may shift the points profile of a user, technically placing certain users outside of their currently achieved level. If so, those users will NOT lose their current level (per our overall strategy) but rather it will take them a bit longer to achieve the next level.
If the increase to occurrences was made for a skill that belongs to a badge, then any user that has already earned that badge will retain the badge achievement.
SCENARIO: Occurrences to Completion is decreased ⬇️
Recall that Occurrences to Completion is the number of successful occurrences to fully accomplish a skill. Points are subtracted for users that already achieved the removed occurrences.
If the removal causes a user to qualify for achievement of the edited skill, then that completed skill is awarded to the user. Subsequently if the completion of that skill completes a badge then the badge is awarded to that user.
Any previously achieved levels and badges are retained even if the removed occurrences contributed to the achievement of those levels and/or badges.
SCENARIO: Skill is removed
For a given user, if this was the last skill to be completed before a badge is achieved then the badge is awarded to that user.
SCENARIO: Skill is added
New skill will equate to extra points which in turn may shift points profile which then may technically place certain users outside of their currently earned level. If so, those users will NOT lose their current level (per our overall strategy) but rather it will take them a bit longer to achieve the next level.
# Same Project Skill Reuse Since skills-service:1.12
In-Project Skill Reuse is a feature that facilitates the reuse of skills within the same project. A skill can be easily reused within another Subject or Skill Group. Reused skills are read-only copies and cannot be mutated. As skill occurrences are reported to the original skill they are also automatically propagated to the reused skills. Changes to the original skill (ex. description, occurrences) are automatically synchronized to all the reused skills as well.
To reuse a skill navigate to the Skills page (
Project -> Subject), then select skills to reuse
and click on the
Action button located on the top-right above the skills' table.
Reuse in this Project button to initiate the process.
Once the skills are reused you will see a
REUSED tag next to each skill.
All the skills under a subject or group can be easily selected for reuse via the
Select All button
# Skill occurrences propagation
Please note that when skill occurrences are reported for an original skill, SkillTree checks whether that skill was reused. For every reused instance the occurrence is queued up to be propagated to that reused skills. The queue is handled in an asynchronous manner so there is a small delay before the skill occurrence are reflected in the reused skills.
# Modify skill in the original project
Only the original skill can be updated. After the attributes of the original skill are mutated they are queued up to be propagated to all reused versions of the edited skill. Please note that skill attribute propagation is performed asynchronously, it may take a few moments for changes to appear in all reused skills.
# Self Reporting and Reused Skills
As skill occurrences are reported to the original skill they are also automatically propagated to all reused copies. Generally skill occurrences are not allowed to be reported against a reused skill copy, after all it is meant to be read-only.
The one exception to this restriction is self-reported skills. Self-reported skills can be reported to the original skill OR to any of its reused copies. Regardless of whether it was reported against a reused copy or the natively declared skill, the points are applied to the original AND all of its copies (assuming points are due based on the current configuration and the reported user's prior contributions). When a self-reported skill occurrence is reported to the reused copy then the request is simply routed to the originally-declared skill. From there on the flow is identical to any skill occurrence that is being reported to the original skill and for every reused instance the occurrence is queued up to be propagated to that reused skills. The queue is handled in an asynchronous manner so there is a small delay before the skill occurrence are reflected in the reused skills.
The Self-reporting "I did it" button is visualized for each reused skill in the Skills Display and Progress and Rankings views.
# Other Considerations
- Skills with dependencies can NOT be reused. Reused skills can NOT be added as a dependency.
- Reused skills cannot be added to a badge; use the original skill instead
- Removing the original skill will also delete all of its reused copies
# Move Skills Since skills-service:2.0
Move Skills is a feature that allows project administrators to move skills to other subjects or skill groups within the same project. When skills are moved, users' points are preserved for those skills and level-based achievements are properly re-calculted for both origination and destination subject/group.
The ability to move skills between subjects gives project administrators gives project administrators the ability to refine their training profile after the initial creation of skills.
To move one or more skills please navigate to the Skills page (
Project -> Subject), then select the skills to move and click
on the Action button located on the top-right above the skills' table. Select the
Move Skills button to initiate the process.
All the skills under a subject or group can be easily selected via the
Select All button