sdavis-awp/planning-poker-salesforce

A Salesforce app that helps you estimate for user-stories in Scrum using a consensus-based, gamified technique called Planning Poker.

Planning Poker App built on Salesforce

1. About
2. Features
3. Technology Stack
4. Installation
   1. Host and Player app for Salesforce Users
      1. Using a package
      2. Using SFDX Commands
   2. Player app for Guests
5. Game Setup
   1. Creating a game
   2. Hosting a game
   3. Playing a game on Salesforce
   4. Playing a game on Heroku
6. Roadmap
7. Building and contributing

About

Planning poker is a consensus-based, gamified technique for estimating user stories in Scrum. This app allows you to utilize this technique for your planning and is completely built on Salesforce.

This Planning Poker app offers 2 custom apps on Salesforce: The Host App and the Player App. Both of these apps can only be accessed by licensed users on Salesforce.

You can optionally also install the guest version of the player app on Heroku to allow players without Salesforce Licenses to paricipate. You'll need a free Heroku account to set it up. A free account lets you run the game with a small group of players. If you run the game with a larger group, consider upgrading to a Hobby Dyno.

Features

1. Choose your own User Story Source Before starting a game, you can select any Salesforce object to be the source of the list of user stories, and save the consensus (Story points) directly to the user story records. 
2. Use pre-defined card sets or create your own This app comes with pre-defined card sets like Fibonacci and multiples of two. You can also create your own custom card sets.
3. Hidden Cards All player's responses are hidden until the timer runs out or until the host chooses to reveal them.
4. Host Controls The host has options to show a timer, hide or reveal cards, reset votes and more. The host can also play the game if they choose to.

Technology Stack

• The Host App and Player App on Salesforce are built using Lightning Web Components.
• The app relies on Application Events, Platform Events and Push Topics to publish game state changes.
  • The Lightning web components use the empApi and Lightning Message service to send and receive these events.
• A combination of Salesforce data and HTML 5 Local Storage is used to maintain game state across page refreshes.
• The Guest Player App is built using Lightning Web Components Open Source and uses Node.js as its backend.
• It communicates with Salesforce using Custom Apex REST APIs.
• It uses the OAuth JWT Bearer flow to connect with Salesforce.
• The Node.js server uses Server Sent Events to deliver notifications to the HTML client.

Installation

Host and Player app for Salesforce Users

Using a package

1. Click the button below to install on Developer Edition, Trailhead Playgroud or Production orgs
   

   

2. Click the button below to install on Sandboxes or Scratch Orgs
   

   

3. Once the installation is successful, Open the Developer Console and go to Debug -> Execute Anonymous Window.
4. Paste the following code, and click Execute

   planningpokersf.PlanningPokerPostInstallScript.insertPushTopics();

5. To make a Salesforce user the host of a game, assign the Planning Poker Host permission set to them.
6. Assign the Planning Poker Player permission set to any users who want to participate as players.

Using SFDX Commands

1. Set up your Salesforce DX environment (see this Trailhead project for guided steps):
   • Install Salesforce CLI
   • Enable Dev Hub on a Salesforce org. You can do that on a free Developer Edition.
   • Authenticate with your Dev Hub org and provide it with an alias (myhuborg in the command below):

     sfdx force:auth:web:login -d -a myhuborg

2. Open a Terminal and clone the git repository:

   git clone https://github.com/adityanaag3/planning-poker-salesforce.git
   cd planning-poker-salesforce

   Tip: you can also download the files from the website if you don't want to install git.
3. Run the installation script. The script deploys the Planning Poker App on a scratch org with a planningpoker alias.

   MacOS or Linux

   sh scripts/setup/orgInit.sh

   Windows

   scripts/setup/orgInit.bat

   Once the script completes, it will open your new scratch org in a browser tab. If you close the tab or get disconnected, run this command to reopen the org

   sfdx force:org:open -u planningpoker

4. To make a Salesforce user the host of a game, assign the Planning Poker Host permission set to them. The above installations script automatically assigns this permission set to the user who runs the script.
5. Assign the Planning Poker Player permission set to any users who want to participate as players.

Player app for Guests

Guests are players without Salesforce Licenses. Here are a few additional steps you need to follow

1. Create a self signed certificate using the command

   openssl req  -nodes -new -x509  -keyout private.pem -out server.cert

2. Create a Connected App in Salesforce with the below configuration
   1. Select Enable OAuth Settings
   2. Use http://localhost:3001 as the Callback URL
   3. Select Use digital signatures
   4. Upload the Certificate generated in the previous step
   5. Select api and refresh_token, offline_access in OAuth Scopes
3. Click on Manage and then click Edit Policies
4. Select Admin approved users are pre authorized in Permitted Users and Save
5. Select Planning Poker Player in the list of permission sets for the policy
6. Deploy to Heroku using the button below
   

   

7. Set the enviroment variables as follows

   Variable	Description
   SF_CONSUMER_KEY	Consumer Key of the Connected App
   SF_USERNAME	Username of the integration user who has been assigned the Planning Poker Player permission set.
   SF_LOGIN_URL	The login URL of your Salesforce org: https://test.salesforce.com/ for scratch orgs and sandboxes https://login.salesforce.com/ for Developer Edition and production
   PRIVATE_KEY	Contents of the private.pem file generated from the certificate creation step
   SF_NAMESPACE	Use planningpokersf if you have installed the host app using the packages listed here. Else, use the namespace from sfdx-project.json file.

8. Update the Heroku App URL record in the Custom Metadata Type Game Settings with the Heroku App's URL generated in the previous step.
9. Optionally checkout the source code for the app here to make modifications or test locally.

Game Setup

Creating a game

1. Create your own Card sets (if needed) by creating new records in the Card Set custom metadata type.
2. Enter the card values separated by a comma. Optionally you can add ? and Pass.
3. Navigate to the Planning Poker Host App, and click on the Games tab.
4. Create a new Game by entering a name and optional description
5. In the "Game Data Sources" section on the Game detail page, select the source of your user stories. If you don't have an existing object where you store the user stories, you can use the "Backlog Item" object that is provided in this app. Here are the values you need to enter if you choose the "Backlog Item" object
   1. Name Field: User Story
   2. Description Field: Notes
   3. Consensus Stored In? : Consensus
   4. List View: All

Hosting a game

1. To start hosting the app, navigate to the Host Planning Poker Tab
2. Select a Game, and click Launch
3. Share the Game Pin shown with the players and Wait for them to join.
4. Once they have joined, click on Start.
5. When the cards are hidden, Players who havent voted are shown in gray color. Whenever a player gives a response, the card's color changes. Once the cards are revealed, the responses are shown.
6. The Host Controls has the following buttons
   1. Save Consensus to save the consensus
   2. Next Story naviagtes to the next story from the list, and also refreshes the players screen with this story.
   3. Reset Cards deletes all the responses for the current story and forces the players to resubmit their vote.
   4. End Game ends the current game for the host and all participants. Once a game ends, it cannot be started again.

Playing a game on Salesforce

1. Navigate to the Play Planning Poker app.
2. Enter the Game Key that the host gives you.
3. Once a user story is shown, click on a Card to cast your vote.
4. Once the host navigates to the next story, your screen refreshes automatically. If not, refresh your screen.

Playing a game on Heroku

1. Navigate to the unique Game URL shared by the host.
2. Enter your name.
3. Once a user story is shown, click on a Card to cast your vote.
4. Once the host navigates to the next story, your screen refreshes automatically. If not, refresh your screen.

Roadmap

• Additional LWC Tests

Building and contributing

If you want to build the project from sources and contribute, run npm install to install the project build tools.