Installing, using, and rolling out the PI Slack app
When each member of a team understands their co-workers needs and strengths, communication and collaboration is more effective and everyone enjoys their work more. The Predictive Index Slack App provides easy access to behavioral insights about co-workers through a simple Slack command: /pi.
Installing the app
The Predictive Index has created a Slack add-on named “The Predictive Index,” also known as the PI Slack App. It enables people to work better with their teammates by accessing PI Behavioral Profile information directly from within Slack by typing /pi commands in the message bar. This is not an application for mobile devices. It’s installed into your Slack workspace and it is used only from within Slack itself.
To get the PI Slack App, ask your Slack workspace administrator and your PI administrator to follow these instructions below. If your team doesn’t have a Slack workspace, create a new one at Slack.com.
Step 1: Make sure your PI account has API Access
The PI Slack App relies on access through the PI application programming interface (API) using an API Key (explained below), but your organization’s PI account must have API Access turned on before any API Key will work. To request this, send a message to firstname.lastname@example.org asking for someone to ensure that API Access is turned on for your account. You can skip this step if you already know that API Access has been turned on. API Access is not normally turned on by default and requires a request to be activated.
Step 2: Obtain an API Key for PI
To use the PI Slack App, you must obtain from the PI software an API Key belonging to a user with the role Account Admin or Account Owner and store this key in the PI Slack App configuration screen in the next step. If the API Key you use belongs to a user with lower permissions, your PI Slack App will not function. If your own PI user account is not an Account Admin or Owner, ask for help from someone on your team whose user account is one of these roles. Only a working API Key is needed to move on to the next step.
TIP: It is often helpful to create a new PI User named something like PI Slack App so that the API Key will not be tied to a real person’s account whose permissions may change over time.
To learn how to create an API Key, see: Generating an API Key.
Step 3: Install the PI Slack App
This step must be performed by an administrator of your Slack workspace. Log in to Slack.com in the same browser as you are using to view this page (not via the desktop Slack app, not via the mobile Slack app) and then click Add to Slack:
You will be asked to grant permission to the The Predictive Index app to access certain information within your workspace. Be sure to approve this access or the PI Slack App won’t work.
Step 4: Complete the App Configuration
You will be prompted to provide a Predictive Index API Key and choose the User Types to include.
API Key: Enter the Predictive Index API Key you obtained in a previous step.
PI User Types to Include: When the PI Slack App receives commands, it will search for PI person data to match the email address of each Slack user it requires. Searching the PI data will go faster if it is limited to only certain types of persons in the PI data. There are three choices presented. If you are not sure which to choose, select the last one:
- Employee – choose this option for optimal speed, but only if you are diligently setting the PI Person Type of all of your workspace users to Employee.
- Employee or Other – choose this option if you have Slack workspace users who are set to PI Person Type Employee or Other.
- Employee, Other, or Candidate – choose this option if you have Slack users who may still be marked as Candidate in PI data even though they area actually Slack workspace users and employees. Choose this option if you’re not sure!
The PI data search is looking for behavioral profile data only, not PI user accounts, so it is not necessary for your Slack users to have a PI user account — any user of your Slack workspace will be able to use the PI Slack App regardless of whether they have a PI user account.
Step 5: Use the App!
As soon as you install the PI Slack App, it immediately becomes available to all the users of your workspace. They don’t need to take any further action to install it, and they don’t need a PI account to use it.
TIP: You may also wish to notify your users about the existence of the PI Slack App by adding a Loading Message (found in Slack Admin > Customize) like this: “Use The Predictive Index slash command “/pi” to better understand your co-workers”.
Step 6: Clean up your PI Data
In order for the PI Slack App to work, the email address stored in each Slack user profile must match the email address stored in their PI person data. Your PI data may or may not be “clean” with regard to matching email addresses. For example, during hiring it is likely that the PI data for your job applicants used a personal email address, but now that some have become employees their email address may need to be changed in the PI software to match whatever company email address they have in their Slack profile.
TIP: To determine which Slack users do not have PI email addresses and Person Type to match your Slack user data, you can issue a /pi-users command. You will receive a list of all Slack users along with information about the quality of match found in the PI data.
Changing the Configuration
There is not currently a place to change the configuration settings you provided during installation. If you need to change the API Key or the User Types you selected:
- Remove the The Predictive Index app from Slack, following the instructions above.
- Install The Predictive Index app again, following the instructions above, making new choices in the configuration step this time.
Installing the PI Emoji Pack into Slack
Why would I want to install the PI Emoji Pack into Slack?
Predictive Index clients who use Slack or another chat-like communication system often find that their conversations about work can be enhanced by referring to PI behavioral patterns and the knowledge surrounding them. One way to bring PI awareness into Slack conversations is the use of PI Reference Profile images as emojis.
The PI Emoji Pack is a collection of icon images available for download.
- Download the PI Emoji Pack and save the file locally.
- Navigate to the download location and unzip/expand the archive so all the images are in a folder together.
- Sign in to Slack as an user who is a member of the Administrator group for the workspace into which you intend to load the emoji images.
- Click on Customize Slack in the main content area.
- On the Emoji tab, usually the first tab displayed below Customize Your Workspace, click on the Add Custom Emoji button.
- Click the Upload Image button, locate the folder containing all the images expanded in step 2, and choose the first one.
- In the Give it a name box, type the name of the image you just chose, something like “:pi-adapter:” NOTE: Whatever name you use here can be typed by users to quickly locate the correct emoji, so keeping a pi- prefix might help quickly filter the list of all available emojis to only the PI images.
- Repeat steps 6 and 7 until you’ve loaded all the emojis.
How do users of Slack make use of the PI Emoji Pack emoji images?
When users want to react to another person’s slack message, they can choose the custom images just like they would standard Slack emoji images, or they can start typing the name to filter the list. If they type “pi”, the list will quickly filter to just the PI emojis. To include one’s own PI Reference Profile image in a Slack status message, type the name enclosed in colon characters like “:pi-captain:” into the status edit box. To include a PI Reference Profile image in a Slack message type the emoji name “:pi-promoter:” into the message box and use auto-complete to choose the right one.
Using the PI Slack app
The PI Slack App uses “Slash Commands”. What is a Slash Command? Slack apps can define “slash commands” which users type into the message bar at the bottom using a forward slash followed by something. For example, the most common command for the PI Slack App is “/pi” followed by a Slack user’s name:
Note regarding visibility: The results of PI Slack App commands are labeled “Only visible to you.” They are seen only by the user who types the command. Other members of the current channel do not see the command or the results you see.
Command: /pi – show PI behavioral info
There are three variations of this one command:
1. /pi @username
For the person specified by @username, displays their name (which is a link to the PI Person Overview), Slack role, reference profile icon + name (which is a link to more information), a one-sentence reference profile description, primary traits of the reference profile, and the Placard for that person.
- View Person in PI Software – Click on the person’s name (e.g. Mike Zani) and go to the PI Software’s Person Overview for that person – this requires you to log in to PI
- Learn About Reference Profile – Click on the reference profile name (e.g. Persuader) and go to the PI Reference Profile explanation and video web page
- Get Person Snapshot PDF – Click on the Person Snapshot PDF button to generate a link to this useful report; the link appears below the other results
- View Placard – Click on the Placard image to view it by itself
- Save or Print Placard – Click on the Placard image, then click on the Open Original icon to open it in your browser, then use your browser to save or print it (change to Landscape orientation and turn off headers & background images)
2. /pi @username1 @username2 @username3
Just like the /pi command above, displays a brief summary for each of the persons you’ve named.
Displays a list of all the members of the current public channel who has PI data (using email as a match), with a Details button for each person. Also displays a list of the channel members whose Slack email did not match a PI person’s email. Use this list to fix your Slack and PI data so the emails match.
Note: This variation of the /pi command only works in public channels, not in private channels or direct messages.
- View Details – Clicking the Details button produces the same output as the /pi @username command.
- View Person in PI Software – Click on the person’s name and go to the PI Software’s Person Overview for that person – this requires you to log in to PI
- Learn About Reference Profile – Click on the reference profile name and go to the PI Reference Profile explanation and video web page
Use the /pi-users command to improve the quality of your data match between Slack and PI. The /pi command relies on an identical match between the email address in a Slack user’s profile and the one in their PI Person data. Even case matters, so JoeSmith@company.com will not match email@example.com. When you issue this command, you will be given a link to a comma-separated-values text file containing the following columns: “Last”,”First”,”Middle”,”Email”,”PI Person Type”,”Folder”,”Match Status”.
- PI Person Type – Employee, Candidate or Other – if you configured the Slack App to only view Employees, then this column might explain why a person’s data is not showing (maybe their PI Person type is not Employee)
- Folder – indicates which folder the PI data for the person resides. You might use this to determine where to find the person you intend to edit in the PI software.
- Match Status – There are three possible values:
- “match” if a single PI person’s email address is found to match the Slack user’s email – no change should be needed
- “no match” if no email address is found in PI data to match the Slack user’s email – fix the case or update the email (from personal to company email?) to make the records match
- “multiple” if more than one PI person’s data is found to match the Slack user’s email – to correct this, merge PI persons who really are one person, archive test persons, or change the email for incorrect persons
Anything you type after the /pi-feedback command will be sent to the PI team along with your team, name, and email. We will only use those to help us understand the context of your feedback.
- Tell us what you think of the PI Slack App!
- Any ideas for new features?
- Something you don’t like about the way it works now?
When you type /pi-about, you will see:
- A summary of what the app is used for
- The version number
- Several links aimed at helping you use the PI Slack App, share it with others, or get help
Rollout strategies to encourage use
- Clean up your data. Give the results of the /pi-users command to a PI administrator who will make sure each employee with a completed PI Behavioral assessment has an email address recorded in their PI person data that matches (exactly!) their email address in Slack. The /pi-users results shows each person’s Slack email, so you know exactly what to store in PI. We are referring to the PI person email seen with Behavioral data for a person (not the PI User email address found under Administration > User Management). Important: Upper-case and lower-case differences matter — the email addresses must match exactly! For example, if one person has firstname.lastname@example.org in their Slack profile, make sure the person data in PI is identical, not a case variation such as JSmith@company.com.
- Be sure your executive team knows about it early. Leaders prefer to be aware of what information others know about them, so be sure to give them the heads-up.
- Informally share the /pi command. Just say, “Hey, come look at this!” followed by a comment about how nice it is to understand co-workers better.
- Mention it in your Slack #general channel. Something like this: “@here Try out this new Slack App from The Predictive Index — just type /pi @yourname (enter) and see what PI says about you. Then check out the same info about any co-worker you would like to understand better.” You might also provide instructions for how they can take the PI assessment if they haven’t already.
- Demonstrate it live in a company meeting. Take 1 or 2 minutes to show Slack on the big screen, type a /pi @username command and point out the results. If you have time, click on the links and buttons to show the other results.
- Mention it in a company email. Include a brief invitation to try the PI Slack App in an general company news email or as a separate message on its own. Include a screenshot. You might also provide instructions for how they can take the PI assessment if they haven’t already.
- Install and use the PI emoji pack for Slack (see above). Begin to make PI concepts part of your company culture by installing the PI emoji pack. It contains images of the PI reference profile icons you can use to fuel your conversations and appreciate the traits people exhibit.
Removing the The Predictive Index App
If you decide to remove the The Predictive Index app from Slack, follow these steps:
Step 1: Go to your Slack Apps list. Log in to your Slack workspace as an administrator. If you’re logged into Slack in a web browser, choose “Administration” > “Manage Apps”. If you’re logged into the stand-alone desktop Slack application, choose “Customize Slack” from the top menu, then “Configure Apps”.
Step 2: View details for The Predictive Index. Look down the list of apps and click the name “The Predictive Index”
Step 3: Click Remove App. Near the bottom of the details view for The Predictive Index app, click the button labeled “Remove App”. Confirm that you really intend to remove the app.
To learn more about the PI Slack App, or if you encounter issues, you can contact the PI Integrations Team at email@example.com.