Jive Advanced Gamification Module: Admin Documentation

Version 65

     

    View the Official setup guide here:

     

    Administering Gamification

     

    How do I Grant Access to the Gamification Admin Console?

     

    Access to the gamification console is automatically given to any admin with the following permission levels in the Jive Admin Console under Permissions > System Administration:

    • Manage System
    • Manage Community
    • Full Access

     

    In some older versions of Jive there may be system permission level named "Manage Gamification" that can be awarded to users without giving them the above levels.

     

    How do I Access the Gamification Admin Console?

     

    Select the arrow next to your name or avatar and you will see it in the list.  Note: This option may not be visible if the user interface enhancements for Gamification are not enabled under Gamification > Basic Configuration in the Jive admin console.  Note: There is also a direct link to the full Nitro Studio console that requires access granted by Bunchball.

    Gamification_AdminConsole.png

     

    Overview of the Gamification Console

     

    Overview - Advanced Gamification Module

    Nitro Studio and API information is also available on the Bunchball documentation site.

     

    Overview of Nitro Studio Analytics

     

    Analytics Walkthrough - Advanced Gamification Module

    Data Export Walkthrough - Advanced Gamification Module

     

    Where are the Activity Stream Notifications?

     

    The default setting for the Gamification module is to not accept inbound REST calls. So if you are not seeing activity stream notifications for users earning badges by completing missions you have two choices.

    1. Leave the Notifications off and don't worry about opening up the firewall.
    2. Open up the firewall and set the following Jive System Property  (Note:  If you're a cloud customer you will not have direct access to the system properties, but these should automatically be set or can be set by Jive.)
      • Jive Admin System Property: nitro.whitelist.ips = 52.35.155.149 - 52.35.155.149, 52.41.137.115 - 52.41.137.115, 52.42.40.97 - 52.42.40.97  (these are the IP addresses you need to allow in)
      • Nitro Admin 'Achievement Callback URL'

     

    How to Change Lifetime Points Balance

     

    1. Look up the Jive UserId in the Jive Admin console (People > Management > User Search).
    2. In Nitro Studio, navigate to Activity & Monitoring > Data Import.
    3. Select Credit or Debit points.
    4. Select the Update lifetime point balance checkbox.
    5. Follow instructions to import new points balance via CSV file. (Note: This can be done in bulk for multiple user IDs, up to 1000 at a time.)

     

    For more import scenarios, see Data Import Walkthrough - Advanced Gamification Module.

     

    Managing Status Levels

     

    In Nitro Studio under Site Settings > Levels you can add or modify the status levels of the community.  These are global levels that are based on points awarded from missions.  Each level can have a custom icon, name, point threshold, description, and action phrase.

    You should update the out-of-the-box status levels as part of your Advanced Gamification Module deployment plan.

    To modify a level:

      1. Hover over the level you want to change and click Edit.
      2. Enter or modify the information and click Save.

    To add a new level:

      1. Click the New level button.
      2. Enter the level information. At minimum, Level name and points are required.
      3. Click Save.

     

    Managing Actions in the Gamification (Nitro Studio) Console

     

    The absolute first thing you should do is check the list of currently available actions here:  Jive Advanced Gamification Module: Action ListThis list includes all valid actions regardless of Jive version. Depending on your Jive version, some actions will not be available to you (For example, Jive 6 does not have skills and endorsements). To see your available actions in Nitro Studio, under Integrate, click Actions.  Note: The list of actions in your console will not automatically include every action in the documentation. You may need to add actions to the console to make them available.

     

    ActionsView.png

     

    You'll want to create folders for your actions that you add to Nitro Studio to help organize them. Typically, you'll name the folders after the actions you're adding. For example, if you're adding actions around ideas, the folder name would be "Ideas".

    To create an action folder:

        1. Click New > Folder.
        2. Enter a folder name and click Save.

    To create an action:

        1. Select the folder you want to put the action in. Alternatively, you can select a folder on the Advanced tab when creating the action.
        2. Click New > Action.
        3. Enter the name of the action as it is listed in Jive Advanced Gamification Module: Action List |Jive Community
          • The name has to exactly match the case and format of the names in the documentation or the module will not recognize it.
          • The format of the action names are as follows:  TheEvent-ACTION_TAKEN-optionalobject (Note: Pay special attention to the case sensitivity and structure of the action name.)
          • The name is the only required part of the action, but it's useful to add a description to each action you add.
          • Prefix Matching: This option allows you to create an action name like ContentEvent and the system matches it with any action that starts with that. For example, when you want to create a mission that rewards the user for creating anything you could use this action instead of specific ones.  You will need to be careful for some actions though as there are "passive" versions of them.  Here's an example:
            • CommentEvent has both a "COMMENT" (you comment on something) and "COMMENTED"  (someone comments on your content) action.  Thus if your action is CommentEvent it will pick up both versions. If you want to be specific, then you'll use actions like CommentEvent-COMMENT- and CommentEvent-COMMENTED- (the extra dash on the end is on purpose!). The dash changes the "prefix" thus ensuring you get the correct actions. If you use CommentEvent-COMMENT and that action has prefix matching enabled, it'll also pick up CommentEvent-COMMENTED so be careful.
        4. Once you've entered any required and optional information, click Save.  Note: Once an action has been used in a mission it displays the missions it's being used in. You cannot delete an action currently being used by a mission.

     

    BlogPostAction.png

     

    How do I Create and Modify Missions?

     

    Missions Walkthrough - Advanced Gamification Module

     

    You create missions in Nitro Studio under Reward & Motivate > Missions. You can create folders to organize your missions. Folders and missions must have unique names. Each mission has 4 pages: About, Who, Rules, and Rewards. Each page has different options you'll have to review. In some cases, pages contain options that Jive will not use.

    About:  The About page has 2 main sections:

    • About - This is where you'll define the name of the mission, the description, what folder the mission is in, and whether the mission is active or repeatable. Note: Team missions are not repeatable.
    • Advanced Details - These are less commonly used, but helpful options. Some options will change if the Repeating option is enabled. If an option is not listed, it's either not used very often or not at all. The following are the most used options:
      • Start and End Date - Each mission can start and end on specific dates. By default, the mission starts as soon as it's created. It can be disabled by clearing the "Make this mission active" checkbox in the About section.
      • Maximum Available - Determines how many maximum points or missions are available. This is useful when you want to do a mission that only rewards the "first x number of people who accomplish it."
      • Send Callback - Controls the activity being pushed to the Jive activity stream when the mission is completed.
      • Daily Maximum (repeating missions only) - Allows you to set how many times per day a user can get credit for accomplishing this mission. This doesn't limit the user's ability to perform any actions in Jive nor does it limit any mission other than the specific mission you're setting this on.

    Who: The Who page defines which users can participate in the mission.

    • Drag a segment, mission, and/or level into the right pane to limit the challenge to those users. Actions are not accumulated until the requirements are met.
      • Segment - Set the mission to be specific to a team. Add a description, set Equals, and click Done.
      • Mission - Set other missions as a requirement to this mission. Until the requirement is met, the mission is not visible or achievable to the user.
      • Level - Requires the user to be at a certain level before they can access the challenge.
    • Toggle the And/Or button between requirements to define if one, or more than one, requirement must be met for the user to participate.

    Rules: The Rules page defines one or more rules that become the requirement for the user to accomplish the mission.This section includes the Action (trigger), the goal for that action (how many times you want that action to happen before the mission is complete), a description of this rule (Note: If you're using 2 or more rules you should include a description for each rule), and any metadata for that rule. Rules also include the mission logic:

    • Must complete ANY of the rules listed (OR) - this means that any one of the rules needs to be completed.  Note:  Missions do not have a running total between 2 or more rules thus you must complete one rule fully to complete the mission.
    • Must complete ALL of the rules listed (AND) - this means all rules must be completed in any order.
    • Must complete ALL of the rules in the order listed (AND) - toggle this option to Yes to require that users complete the rules in the specific order listed in the mission. These types of missions can be more difficult to complete and thus should have very good descriptions.

    Rewards: The Rewards page defines what users get for completing the mission based on defined rules.

    You can give points, badges or items, or do a combination of things.

     

    How do I Create a Mission that can Only be Accomplished in a Specific Place or for Specific Content?

     

    Every mission can be tied to a specific place or piece of content. Missions cannot be tied to a specific user, unless the user is being identified as a User Container. The actual process of making the mission specific to a place or content is adding metadata to the rule(s) of the mission.  Each rule can have only ONE (1) set of metadata applied to it (thus you can tie a rule to only 1 space, group, project, or piece of content). Note: Nitro Studio does not follow space hierarchy and sub-space structure so a rule applied to a specific space is for THAT space only, not any sub-spaces to it. If you want to add a rule to the sub-spaces you will have to create a separate rule for each sub-space.

    See the metadata cheatsheet for additional help with custom missions.

     

    Metadata is two pieces of required information used to define exactly what object you are applying a rule to. Depending on the object (place vs. content) there will be different options:

    Metadata for Spaces

      • containerType = community
      • containerID = found by copying containerID #### during creation of content.

    Metadata for Groups

      • containerType = socialgroup
      • containerID = found by copying containerID #### during creation of content.

    Metadata for Projects

      • containerType = project
      • containerID = found by copying containerID #### during creation of content.

    Metadata for User Container

      • containerType = usercontainer
      • containerID = found by copying userid #### when searching for the user in the Admin Console.

    Metadata for Specific Content

    The values for type are the human readable names for the content:  thread (for all discussions), document, blogpost, idea, video, poll, event, message (for discussion replies)

      • type  (lowercase)
      • id   (lowercase)

    Metadata for Tags

      • tagname can be applied across content, users, places.
      • tagname may look for a text based value or an ID depending on the setting within Admin > Gamification > "Send Tag IDs"
        • The [name] you use is 'tagname' lowercase
        • The [value] you use depends on the above admin setting, and can be the tag's actual name or ID

    How do I get the metadata information?

    For Spaces, Groups, Projects

    If you're trying to get the containerID:

    1. Navigate to the space, group, or project in your community.
    2. Click the "Start a Discussion" action or any other type of content in that place.
    3. Note the URL of this page. It will contain the containerID. Record that 4-5 digit number.
    4. IMPORTANT:  You will also see a containerType value in that URL. Ignore that and DO NOT use it in metadata. Use what is listed above!

    ContainerID.png

    For Users

    If you're trying to find a person's userid:

    1. Navigate to Admin Console: People > Management > User Search.
    2. Search for the user.
    3. Copy their userid.

    For Content

    If you're trying to get the ID of the content:

    1. The content has to be created before you can create a mission for it.  For content such as documents and blog posts that have draft forms, that is sufficient.
    2. Navigate to the content and for all content other then blog posts (we'll cover them next) you can use the ID number in the URL directly.

     

    ContentID.png

    Note:  Discussions have 2 possible ID numbers. One is for the thread itself (see above) and the other is for replies. While it's not typical to gamify a reply, it can be done.  (Note:  If you're trying to create a mission that rewards the user for replying to a specific thread you'll use the thread's ID number like above). In the following screenshot, the actual ID number is 2039 though it is listed twice.

     

    ThreadID.png

     

    Blog Posts:  Blog posts are special in that their URL does not include the ID number, but instead is tied to the blog and the content title. So in this case you'll have to edit the blog post and when you do the ID will be present in the edit URL.

    BlogPostID.png

     

    How do I Apply the Metadata Information?

     

    Metadata is applied in each rule that you want to tie to a specific place or piece of content. You can add metadata while creating a mission or by editing an existing mission.

    In Nitro Studio under Reward & Motivate > Missions > create a new mission or edit an existing mission > Rules tab.

        1. For each rule in the mission, expand the Advanced Options section (if editing, click Edit first).
        2. Enter in the first part of the metadata
          • For places:  [Name] containerType; [Value] community, socialgroup or project depending on what type of place it is
          • For content: [Name] type; [Value] the human readable name of the content
          • For tags: [Name] tagname; [Value] the tag's plaintext name. For example, if I want to reward users for tagging content with 'knowledgebase', make knowledgebase the [value].
        3. Click Add More Metadata Rules.
        4. Enter in the second part of the metadata
          • For places:  [Name] containerID; [Value] the ID of the place
          • For content:  [Name] ID; [Value] the ID of the content
        5. Click Done. The following shows how the metadata looks in the rule.

    Important:  All metadata is CASE SENSITIVE. Any error in the case, name, or ID number result in the mission not working. If you're testing and it doesn't work, reference this image and verify it looks correct, then check your actual ID number!  All values of metadata are lowercase.

     

    MetadataRule.png

     

    Can you Manually Assign a Mission to a User?

     

    You can manually assign a mission to a user, but when should you? Do this when you need to reward for things outside of Jive. However, this is a very manual tedious process so use it lightly.  Any mission can be manually applied to any user as long as the mission is active. If you don't want the user to automatically accomplish the mission (for example, a mission to reward a user for getting a certification) you need to create a "fake" action in Nitro Studio. You'll follow the same steps as detailed in the "How do I create and modify missions?" section of this document, but the action name will not match anything in our documentation. A commonly used name is "Nonexistent Action" or "Manual Action".  You can name it "Bob" if you really want to as long as it's not something listed in Jive Advanced Gamification Module: Action List |Jive Community. Create the mission just like any other mission, but in your rule you'll use your fake action. This will ensure that no user can complete the mission as the system will not recognize it, thus it will never "fire". In my screenshot I used a fake action named ManualBadge-ASSIGN (for those who want to follow the action naming conventions), but since it's not in our documentation it'll never actually "work" on its own.

     

    ManualAssign.png

     

    How do you assign it to the user once it's created?

     

    You'll need one piece of information to do this: the user's Jive Userid.  This can be found in the Jive Admin Console under People > Management > User Search.  This should be a 4+ digit number.  Note: You need the Userid not the Username. Once you have that go back to Nitro Studio.

        1. Once you have the Jive Userid, return to Nitro Studio (Activity & Monitoring > User Lookup).
        2. Enter the Userid in the Lookup user by id field > press Enter.  Note: Nitro doesn't know any profile information about the user just the userid and the gamification information.
        3. Click the Missions tab and you'll see the missions ordered alphabetically.
        4. Expand the appropriate mission.
        5. Click Complete Challenge.

    UserID.png

     

    How do I Change the Sort Order of Missions in the Jive UI

    You can determine a default sort order for missions in Nitro Studio under Reward & Motivate > Missions > New button > Mission Ordering link. On this screen,  drag and drop missions into the desired order, and then click Save to apply the changes. Note that the end user has the option to order their Missions view in other configurations (alpha, completed, incomplete, etc.) which overrides the Admin-specified ordering.

     

    How do I create Teams?

    Missions Walkthrough - Advanced Gamification Mo... |Jive Community

     

    What are Teams?

    • As a user, you can join a team to compete against other teams. Rather then just collecting points for yourself, you now gain points towards team missions as well as your personal missions.
    • For example:
      • You navigate to a group that's highlighting all of the teams in the community.
      • You join a team 'West coast team' and see a mission "Answer 20 questions".
      • You and 5 other people in 'West coast team' collectively work together to answer 20 questions in a Jive community and win the competition vs the East coast team.
      • Your team gets the reward for the team mission, and your team point total is updated in the Team Leaderboard.

    Creating a new team

    1. In the Gamification Console (Nitro Studio) go to Configuration > Groups.
    2. Select the folder you want to create a new team under.
    3. Click New > Group.
    4. Name your team and click Save.

    Add some properties to your group like a team logo:

        1. Double-click the group you wish to modify
        2. To add a team logo click the New button
        3. Enter photoUrl in the "Name" field and the URL to the image in the "Value" field
        4. You can also add the following properties:  groupName, groupDescription

     

    How do I Manage the Store?

    • The store can be activated / deactivated from the Jive Admin Console.
    • Purchases in the store send a notification to the admin if the following property in Nitro Studio  is configured: Configuration > Site Settings > General > Item Purchase Notify URL  (http://wwwadmin.bunchball.com/jive/JiveEmailCallback.php?email=none@bunchball.com    add your email here).
    • To create new items from Nitro Studio, navigate to Catalog Items > Store folder > New > Catalog Item.
    • There is no automation of reward handling currently built into the system. The items in the store display in Jive, deduct 'purchase points' (separate from other points), and disappear  from the store once purchased.
    • After purchase, the user who is notified must go into Jive and manually assign rewards to the person who purchased an item. See the "How do I manually assign a mission to a user" section.
    • Please ensure that you have Bunchball's mail servers whitelisted if you don't get the emailed report (Bunchball's Mail Host IP Address):
      • 52.35.155.149
      • 52.41.137.115
      • 52.42.40.97
    • Looking at bunchball.net - 1 MX Records, 2 SPF Records - ReverseMX.com, there is one MX record and four SPF records.

     

    How to Back Up your UAT and Copy those Settings into your Production Gamification Instance

     

    Use the Gamification Console (Nitro Studio) to perform Nitro backups, or to migrate UAT to Production environments.

     

    Create an OAuth Client

    1. Open the Gamification Console (Nitro Studio) > Configuration > Site Settings > OAuth.
    2. Click New Client.
    3. In the Name field, enter a descriptive name.
    4. In the Scopes field, select the access you need:
      • fl backup - Minimum access needed to back up a site. Also grants access to delete a backup.
      • fl restore - Minimum access needed to restore a site.
    5. Click Save.

    Create a Backup

    1. Log in to the site that you want to back up.
    2. Open the Gamification Console (Nitro Studio) > Configuration > Site Settings > Backup & Restore.
    3. In the OAuth Client field, select your OAuth Client.
    4. Click Backup.
    5. In the Name of Backup field, enter a name for the backup, and then click Generate Backup on Server.
    6. If you are planning to restore the backup immediately, click Copy site configuration to Clipboard?. Otherwise, click Cancel.

    Restore a Backup

    1. Log in to the site where you want to restore a backup.
    2. Open the Gamification Console (Nitro Studio) > Configuration > Site Settings > Backup & Restore.
    3. In the OAuth Client field, select your OAuth Client.
    4. Click Restore.
    5. Do one of the following:
      • If you copied a site configuration to the clipboard, click XML Text, paste the configuration data, and then click Restore.
      • If you do not have site configuration in the clipboard, click Backups on Server, select a backup in the list, and then click Restore.
    6. Click Yes to confirm.

    System Properties Reference

     

    The following system properties are available in the plugin.  Most of these should not be modified without guidance from Jive.

     

    Property Name
    Default Value
    Takes Effect...
    Description
    nitro.http.soTimeout1000ImmediatelyThe socket timeout setting used when communicating with the Nitro service.  Specificied in milliseconds
    nitro.http.connectionTimeout1000ImmediatelyThe connection timeout setting used when communicating with the Nitro service.  Specified in milliseconds
    nitro.retry.sleepTime60000ImmediatelyThe amount of time the retry worker will wait before polling the queue for requests to retry.  Specified in milliseconds
    nitro.retry.batchCount100ImmediatelyThe number of requests the retry worker will pull from the queue each time it runs
    nitro.client.ignorableErrorCodes207ImmediatelyA comma separated list of Nitro Error Codes that we ignore and will not cause a request to be retried
    nitro.user.disabled.preferenceNameAnonymousImmediatelyThe name of the user preference we set in the Nitro service for deactivated users
    nitro.event.excludedUserIDs1ImmediatelyA comma separated list of user IDs to exclude when sending activity.  This is used to exclude system accounts from the module.  This should always include user ID 1
    nitro.whitelist.ips52.35.155.149 - 52.35.155.149, 52.41.137.115 - 52.41.137.115, 52.42.40.97 - 52.42.40.97ImmediatelyA comma separated list of IP address ranges that are allowed to invoke the achievement callback web service
    spring.nitroConversionQueueConfiguration.numWorkers5After restartThe number of worker threads available for the conversion work queue
    spring.nitroConversionQueueConfiguration.queueSize1000After restartThe size of the conversion work queue
    spring.nitroDeliveryQueueConfiguration.numWorkers5After restartThe number of worker threads available for the delivery work queue
    spring.nitroDeliveryQueueConfiguration.queueSize1000After restartThe size of the delivery work queue