Category: Predictive Index

PI2 Upgrade Preparation Options

Believable Magic has been receiving inquiries from PI Network Partners and Customers to determine which of the tasks associated with upgrading to PI2 we can help with.

Here is our analysis of the Software upgrade support guide provided by The Predictive Index.

Prepare for upgrade – Preparation Checklist

In the Upgrade Preparation Checklist, PI has outlined several steps to be taken. Here are the ways Believable Magic can help with each of them:

Take Action

The actions suggested by PI essentially involve manual use of the PI software to make changes to individual records, fields, and any items that can be bulk-selected for action (bulk archive, bulk move, bulk export).

Action Suggested Strategy Analysis Believable Magic Alternative
Account hygiene Remove former employees, candidates and jobs you no longer need  Painful process of choosing, selecting, archiving, and/or editing persons and/or their assessments in the PI software Buy MagicTools or get PI Data Cleanup Service – use Clean Expired BAs, Clean Duplicate BAs, and Export-Adjust-Sync person data to mass-archive or mass-update many records at once. Jobs must be manually managed via the PI software.
Account hygiene Downloading assessment data using PI software PI data export has few columns, doesn’t include the Score ID needed to later re-create accidentally archived data Buy MagicTools or get PI Data Cleanup Service – use Export Person and Assessment Data to obtain a much larger array of assessment data including individual sigma values. You can also Export BA Reports to PDF for all your people to keep as an archive before making changes.
Review your employee emails Manual process of finding each person, editing, and updating them in PI software Painful manual process of searching, editing necessary fields, and saving each employee. Buy MagicTools or get PI Data Cleanup Service – export your HR data, prepare it a little, and then use the Sync process to match and fix employee person data in PI.
Review your folders Manually edit the Folder structure Removing a folder requires that you first archive or move all contents, a potentially very laborious process Buy MagicTools or get PI Data Cleanup Service – use Export Folders to get a clean list of your current folders, make a plan, then use Export-Adjust-Sync process to move all your people/assessments to their new folders, then delete any unused.
Review and prepare your Open Invitation (OI) Links Legacy OI Links that are linked to Jobs will be converted to the new Job Links and continue to work as they do now. OI Links that are not linked to a Job will cease to work. This is a manual process of analyzing your OI Link use outside of PI and then creating Job Links in PI2 to fill any gaps. We don’t offer any service or tool to make this easier.

Alternatives We Offer

Buy MagicTools and do the work yourself

If you license MagicTools for a 90-day period right now and install the software on your local system. Use its Clean, Export, and Sync processes to bring order to your PI data before making the PI2 transition. Follow guides in Learn MagicTools and the Knowledgebase.

Get the Predictive Index Data Cleanup Service

Priced according to your PI headcount, the PI Data Cleanup Service is a consulting service performed by Believable Magic in collaboration with your team by using MagicTools to connect to your PI data. It includes automated cleanup processes for expired and duplicate assessments and bulk data updates through a multi-step Export-Adjust-Sync process of exporting data, making adjustments, and then using MagicTools Sync process to push those changes into PI data. 

Export-Adjust-Sync Process

  1. Export – Export your HR system data to gather employee and/or candidate details, and use MagicTools Export to obtain your PI person data so you can understand what you are working with.
  2. Adjust –  Make necessary bulk adjustments to your employee and/or candidate data to prepare it for…
  3. Sync – Use MagicTools Sync process to import the contents of the HR data file, find matches wherever possible, and then change the PI data to match the HR data file contents — assign the correct person type, correct email, correct folder, and even fix name variations.

 

PI API Key Testing and Troubleshooting

Predictive Index customers who wish to use the PI Application Programming Interface (API) to access their PI data must generate and use an API Key. Once generated, it is often useful to test the API Key to learn whether it works as expected.

This article provides guidance for testing and troubleshooting PI API Keys.

Testing a PI API Key

Test any Predictive Index API Key through the API Reference site published by The Predictive Index (referenced on the PI Developers site). 

Does it work at all?

A good test method to choose is “GET Behavioral Assessments” which will read up to 50 existing behavioral assessments:

  1. Open this page: https://pi.predictiveindex.com/swagger/ui/index#!/BehavioralAssessments/BehavioralAssessments_GetBehavioralAssessmentsV2(opens in a new tab)

  2. Paste the API Key into the upper-right box in the header of the web page (NO need to click Explore)

  3. Scroll down to the “Try it out” button at the bottom of the GET Behavioral Assessments section and click it

  4. Scroll to the Result below the button and see what it says

    1. If the Result shows assessment results (in JSON format), your API Key works!

    2. If the Result section shows a 401 error, the API Key is not working correctly. See Troubleshooting below…

Does it do everything I need?

What do you need the API Key to allow you (or the software using the API Key) to do?

  • Read Basic Data – If you intend to use the API Key to simply read data available to the PI User that owns the API Key, the test above will be enough.
  • Read All Data – If you intend to use the API Key to read ALL the data in the PI instance, then the PI User that owns the API Key should be given an elevated role such as Power User or Account Admin. If your instance of PI also utilizes Cognitive Assessments, you may need to grant Cognitive Access to the API Key User, too.
  • Create and Modify All Data – If you intent to use the API Key to not only read existing data but also to create and send new assessments and invitations, to change Person data, and/or to Archive assessments, then you must assign the API Key Owner the role of Account Admin or Account Owner (and grant Cognitive Access if your instance uses the Cognitive Assessment).

To test whether the API Key is correctly configured to do “all you need it to do”, you must test several of the intended actions that will be taken by the system using that API Key. Here are some additional tests you might perform:

Create a Person and Send a Behavioral Assessment

Use the POST Behavioral Assessment method. This method can be used two ways: to send an assessment for an existing PI Person, or to create a new PI Person and send them an assessment. The example below will do the second: create a new PI Person and send them a behavioral assessment:

  1. Open this page: https://pi.predictiveindex.com/swagger/ui/index#!/BehavioralAssessments/BehavioralAssessments_PostBehavioralAssessmentBybehavioralAssessmentToCreatedirectToNewSurveySite

  2. Paste the API Key into the upper-right box in the header of the web page (do NOT click Explore)

  3. Scroll back down to POST Behavioral Assessment method

  4. Create a request payload using a real email address at which you can receive the assessment invitation and put it into the “behavioralAssessmentToCreate” space. Here is a sample (it must be in JSON format, as shown):

    1. {
  "notifyAssessmentAvailableUsingEmail": 1,
  "firstName": "API Key",
  "lastName": "Tester",
  "email": "somerealemailaddress@domain.com",
  "personType": "Other"
}
  5. Click the “Try it out!” button
  6. Look at the HTTP Response Code in the Response section.
    1. If it is “201” then you have been successful and your API Key can be used to create/send assessments
    2. If it is anything else, then you have either:
      1. Introduced a syntax error in your behavioralAssessmentToCreate payload
      2. Used an API Key whose PI User does not have permission to send assessments. To resolve this, go into the PI software, find the user, and change their role to Power User or Account Admin.

Archive an existing Behavioral Assessment

Use the DELETE Behavioral Assessment by ID method to send an archive command for a behavioral assessment. This will soft-delete the person and all their assessments and make it impossible to read their data via the API or the PI software, so do not test this on a real person whose data matters to you!! The only way to recover soft-deleted data is to ask PI Support to help you.

  1. Use the GET Behavioral Assessments method shown in the “Does it work at all?” section at the top of this article to get results.
  2. In the Results of that method, find an assessment you are okay to archive. For example, if the assessmentState = 50, that assessment expired and is no longer of any use. If the assessment was sent long ago, it is probably safe to archive it. When you have found an assessment to archive, copy its assessmentId to a temporary location.
  3. Open this page: https://pi.predictiveindex.com/swagger/ui/index#!/BehavioralAssessments/BehavioralAssessments_DeleteBehavioralAssessmentByIdByid

  4. Be sure your API Key is in the upper-right box in the header of the web page (do NOT click Explore)

  5. Scroll back down to DELETE Behavioral Assessment by ID method

  6. Paste the assessmentId you copied in step 2 into the field labeled “id“
  7. Click the “Try it out!” button
  8. Look at the HTTP Response Code in the Response section.
    1. If it is “204” then you have been successful and your API Key can be used to archive assessments
    2. If it is anything else, then either:
      1. The assessmentId you specified is not correct. Did you copy/paste it correctly? Did you archive it previously? or
      2. The API Key whose PI User does not have permission to archive assessments. To resolve this, go into the PI software, find the user, and change their role to Power User or Account Admin.

Troubleshooting an API Key Problem

401 Error

A 401 error with a PI API Key usually arise when one of the following has occurred:

  1. The API Key belongs to a PI User who has been deactivated by accident.
    1. To resolve this, log into PI software as an Account Owner or Account Admin and go to the Administration > User Management view. Find the API Key owner in the list and ensure the activation switch is toggled ON.
  2. The API Key has been replaced because someone clicked the “Generate” button which creates a new API Key for the PI User and invalidates the old key that you are using.
    1. To resolve this, find the new API Key that was generated for this PI User and start using it instead of the one that was failing.
  3. The PI Instance/Account does not have API Access turned on. It is possible to generate an API Key even when API Access is turned off.
    1. To get API Access turned on, submit a request to integrations@predictiveindex.com and include the name of the PI Instance/Account. Once API Access is turned on, normally it should not be turned off by PI, but anything is possible.

Generating a PI API Key for PI v1

Predictive Index customers who wish to use the PI Application Programming Interface (API) to access their PI data must generate and use an API Key.

API Keys are “owned” by individual PI Users and are not assigned or created as a company-wide setting. The role and permissions of the user that owns an API Key determines the access that API Key will grant.

This article explains how to generate an API Key for accessing the data of an instance of the PI version 1 software.

To learn about PI version 2 software’s API Key features, see: Managing Open API Settings (PI version 2 docs)

Activate API Access

Your organization’s PI instance must have API Access turned on before any API Key you generate will work. Contact Predictive Index Support and ask them “Please ensure that API Access is turned on for our PI instance named _____”.

As of the time of this writing, API Access activation process and the use of the PI API does not currently cost anything extra for existing PI customers.

Where to Generate API Keys

API Keys are generated in the PI Software’s Administration > User Management area.

This administrative action can be taken only by PI Users with the role of Account Admin or Account Owner.

How to Generate an API Key

Refer to the PI Support site for general guidance on how to generate an API Key: Integration Guide > Generate an API Key.

Or you can follow this example:

Example – API Key for user named Data Manager

Steps to take if you decide to create a new user named “Data Manager” to own an API Key for use with MagicTools or an API Integration:

  1. Log into PI (https://app.predictiveindex.com) as an Account Admin or Account Owner user with whatever email and password you normally use.
  2. Go to Administration (on the menu seen when you click your name in the upper right corner).
  3. In User Management, click “Create New User”.
  4. Give the user the following details:
    1. First Name: Data
    2. Last Name: Manager
    3. Email: data.manager@yourdomain.com
      1. Note: no two users in the entire PI system can have the same email address
      2. Use a real email address if the user you are creating will need to log into the PI software directly
      3. Invent any fake email address if the user will not log into the PI software — as long as the email has not been used previously in the PI system and this user will only ever use the API Key to access PI data.
    4. Job Title: (optional)
      1. When using MagicTools: MagicTools Connection
      2. When using an API Integration: Integration with XYZ (the name of the system you are integrating with)
    5. Default Folder:
      1. When using MagicTools: \Your Company (type the backslash and then choose the first item shown in the suggestion list).
      2. When using an API Integration: choose a default folder into which new assessments/users will be created by the integration. If the integration will specify a folder, this is not as important. But if the integration doesn’t specify a folder, this is an important decision.
    6. Role: Account Admin – this elevated role allows the API Key to do things like archive unwanted data and move people to new folders.  
  5. Click “Create User” – you will be taken back to the list of all users.
  6. Click on the name of this new user in the list of users so you can view/edit the user details again.
  7. At the bottom, you will see a new “API Key” field that wasn’t there before you created the user.
  8. Click the “Generate New Key” button. 
  9. Click the little icon next to the API Key field to copy the new API Key to the clipboard.
  10. Paste the API Key into a document and save it to a secure location. Remember: an API Key is a powerful thing — guard it!
  11. Click “Save Changes” if you made any changes other than generating the API Key. Click “Cancel” if the Save Changes button is disabled — newly generated API Keys are automatically saved when you click Generate, so there is no need to click Save Changes if generating an API Key is the only action you are taking.

Granting Cognitive Assessment Access

If your organization uses the PI Cognitive Assessment, be sure to read this section.

Because the Cognitive Assessment is considered sensitive personal information, access to results is usually limited to a small group of hiring team members. If the API Key you are generating will be used by a system or tool (such as MagicTools for PI) that needs to access Cognitive Assessment data, that permission must be granted by someone with “Account Owner” permissions. A user with “Account Admin” access does not have the ability to grant permission. Therefore, be sure to contact a user with “Account Owner” access to have them activate Cognitive Access for the user you created as the owner of the API Key. While editing a user’s profile/details, Account Owner users will see a checkbox that grants access to Cognitive data.

Testing an API Key

It is always best to test your new API Key before sharing it or using it. Learn how to do this here: PI API Key Testing and Troubleshooting

Sharing an API Key with others

Because API Keys grant powerful access to semi-sensitive information, take precautions to protect them. Some choices:

  • Use a temporary encrypted sharing tool like the one offered by Believable Magic: Securely Share Sensitive Content
  • Save the API Key in a document that is stored in a shared location accessible only to you and the intended recipient

Generating a new API Key

If you have already created an API Key for a user and then use the “Generate New Key” button to generate a new API Key, the previously generated API Key will be deactivated immediately. Any integration or other data access function that was previously configured to use the old API Key will be disabled by this action. Generating a new API Key is necessary when you wish to disable access by people who might possess a current API Key and ensure that only the new API Key is usable. Be sure to immediately share the new API Key with whoever controls the configuration of any integration that relies on that Key! 

Get a Predictive Index Sandbox Account

Organizations with a subscription to The Predictive Index platform are typically able to request access at no extra charge to a separate Sandbox account for use in learning and testing PI functionality. Sandbox accounts are frequently requested by customers who are using the API to create some kind of integration with PI.

Note: The Predictive Index only responds to Sandbox requests originating from customers themselves, not from third-parties working on behalf of a customer. The steps below should be followed by the customer contact with authority to submit support requests to PI.

To obtain access to a Sandbox account…

  1. Send an email to PI Customer Integration Support: integrations@predictiveindex.com
    Your request should include content like this:
Hello PI Integrations Team,

I am an authorized account manager for the following PI account:
XYZ Company
Please grant me administrative control of a Sandbox account for XYZ Company, naming (or if one exists, renaming) it:
XYZ Company Sandbox

We will be using this to develop and test an API integration with System ABC, so please activate API Access for this Sandbox account.

Please ensure that the Sandbox account has all the same assessment types and features activated as our Production account so that we can fully test.

Please create an Account Owner user:
First Name: XYZ Sandbox
Last Name: Talent Team
Email: noreply-sandbox@xyzcompany.com

Please provide me with the password for this user since we are assigning an email address without an inbox which will make it impossible to use password recovery via email.
  1. Log in to PI as the user at: https://app.predictiveindex.com
  2. Go to the Administration > User Management view
  3. Find your user in the list and click on it
  4. Select a default folder into which assessments/persons created by this user will be placed (unless a different folder is specified at the time an action is taken)
  5. Generate an API Key and copy/paste it somewhere safe
  6. Save your settings
  7. Securely share the API Key with the person(s) who will be developing your API integration.

Remember: API Keys grant complete access to the data and features available to the user with whom it is associated.

For more Believable Magic advice about creating and managing API Key owner users, see: 

For more Predictive Index info about PI API Keys, Sandbox accounts, and PI Integrations in general, see: