Data That MagicTools Can Change

MagicTools – for PI can read, export, and change data within your organization’s PI instance. This article explains which data can be changed.

Data Archived

The PI software platform uses an “archive” model in which data is marked as hidden and becomes irrelevant to end users. There is no action that will lead to the actual permanent deletion of a person or assessment.

PII Anonymization Note: At the time person data is archived in PI, any personally identifying information (PII) present remains within the archived data. Since this would not be acceptable under current privacy laws, the PI platform offers an Anonymization feature that will remove all PII before archiving that data. MagicTools also performs anonymization of PII whenever it archives person data.

Assessments – Yes

MagicTools will archive Assessments as part of the following actions:

  • Clean – Expired Behavioral Assessments
  • Clean – Multiple BA’s for Persons with same email – keep only the oldest

Persons – Yes

MagicTools will archive and anonymize Person data as part of the Clean actions mentioned above but only when this additional setting is selected:

  • Anonymize and archive Persons who have no remaining BA’s

And the following is not checked and applicable to that organization and person:

  • But not Persons who still have a Cognitive Assessment

Data Changed

Assessments – No

MagicTools cannot modify any PI Assessment data at all. It can Archive entire Assessments, but cannot change their individual data elements after they have been created and/or completed.

Persons – Yes

MagicTools can modify the following PI Person data as part of the Sync process:

  • First Name – cannot be blank
  • Middle Name – cannot be changed to blank if a value exists — changed to a period (“.”) if the new value should be blank
  • Last Name – cannot be blank
  • Email Address – cannot be blank
  • Job Name – optional – cannot be changed to blank if a value exists
  • Person Type – Candidate, Employee, Former Employee, Other, Unknown
  • Folder Path – Location in the folder hierarchy (which also influences access permissions by PI users)
  • External Person ID – an optional field containing an identifier taken from some external system and associated with a single PI Person

 

Using PI API Keys in MagicTools

MagicTools – for PI gains access to your organization’s PI data by using an API (Application Programming Interface) Key.

An API Key is always generated in connection with a specific PI User account:

  • The actions taken within MagicTools using an API Key are dependent on the permissions granted to the PI User who “owns” the API Key.
  • All actions taken via MagicTools will be attributed to that PI User in the PI software.

Therefore, when deciding which PI User should own the API Key you’ll use with MagicTools, consider the following:

Current vs. New User

  1. It may be best to use your own existing PI User account to generate your API Key if you want all actions you take with MagicTools to be attributed to you. With this approach, the actions you take while logged in directly to PI and those taken through MagicTools cannot be distinguished from each other when viewed in the PI software.
  2. It may be best to create a new PI User that you intend to use only with MagicTools so that you can tell the difference between actions taken while signed into the PI software directly and those taken via the PI API and MagicTools. You might put the term “API” or “MagicTools” into the name of the user you create for this purpose.

User Role

  1. If the API Key belongs to an Account Owner or Account Admin user, MagicTools will have access to all person and assessment* data in your PI instance and to perform any actions on that data that are possible via the API.
  2. If the API Key belongs to a Power User, User, or Read-Only user who has access to only some of the person and assessment* data, MagicTools will only be able to read or modify the permission-controlled set of person and assessment data available to that user.

*Note: Keep in mind that access to Cognitive Assessment Data requires separate access to be granted if you intend to allow a user this permission.

Generating an API Key

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 organization”.

Where – 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 – Follow the instructions in the following PI Support site to generate an API Key: Integration Guide > Generate an API Key.

Securing MagicTools – for PI

Installation

Application – “MagicTools – for PI” is a Windows application named MagicTools.exe that is installed locally on a Windows computer or within a Mac Parallels virtual Windows environment on a Mac computer. It relies on the .NET framework and several library files installed along with the main program.

Installer – It is installed using an executable installer program, MagicToolsforPISetup.exe, which is created by Inno Script Studio.

Code Signing – The software is signed by a code-signing certificate issued to Believable Magic LLC by Sectigo RSA Code Signing CA.

Configuration

User Settings – Configuration settings are stored locally for each user of the software in a folder only accessible to that user. For example:
C:\Users\{username}\AppData\Local\Believable_Magic_LLC\MagicTools.exe_Url_{uniqueId}\1.3.4.21246

Upgrades – After upgrading MagicTools software, when the software is first started up, a new settings file is created in a folder named for that version by copying the previous version’s settings file forward.

Unencrypted – Configuration settings are stored in an unencrypted state to make it convenient for a user to review their own settings file contents if necessary.

Settings

Two of the settings displayed in the Setup tab within the MagicTools software and stored in the configuration file are considered sensitive:

  • MagicTools License Key – this key is obtained from the seller and is used to validate that the current user is licensed. MagicTools makes a web service call to an endpoint on the believablemagic.com server to validate the current license key. It is the responsibility of the licensed organization to put this key only into the hands of people who are authorized to use the MagicTools software on behalf of the organization.
  • Predictive Index API Key – this key is generated within the administrative user interface of the PI Software by a Site Admin or Account Admin user of the PI software. Any actions taken via MagicTools using this API Key are recorded within the PI software as actions of the API Key owner. This key is considered sensitive data because it grants access via the Predictive Index API to data stored in the PI software. Learn more about: Using PI API Keys

The sensitivity of the PI API Key described above is the reason that Believable Magic recommends the following two guidelines:

  • For PI Users – MagicTools – for PI is intended for use by those individuals who have already been entrusted with access to the organization’s PI data via a PI user account.
  • Individual API Keys – MagicTools users should each be given an individual PI API Key that is associated with an assigned PI user account so that they may access and modify the same data via MagicTools as they are able to access and modify through the PI software directly.

No New Permissions – API Keys don’t have more power than their users do. Providing an individual API Key to a trusted PI user does not extend their access and control privileges, it only enables them to use those privileges more efficiently and powerfully through MagicTools.

API Access Required – API Keys are only useful to PI client organizations that have API Access turned on. PI clients may ask the PI Support team to turn on API Access for your organization if this has not already been done.

Securing the Data

No Internet Storage – All data processed by MagicTools is directly accessed via the Predictive Index API over the Internet from the local computer, storing no data on any other system anywhere on the Internet apart from the local computer running MagicTools.

No Believable Magic Access – Believable Magic systems never handle or touch the PI data handled locally by MagicTools.

Local Output Files – MagicTools generates log files and (optionally) export files that contain plain text copies of whatever PI data is handled by the actions being taken by the user. All of these log and export files are placed into a user-selected Processing Output Location folder.

Output File Disposal– It is the end user’s responsibility to ensure that any log and export files are properly disposed of after they are no longer needed.

Setup Tab Configuration

Every time the MagicTools – for PI software is launched, it checks whether the Setup tab contains all the things needed to run. If it finds anything missing, the Setup tab will display first.

After you’ve provided everything in the Setup tab, the next time you start MagicTools it will display the Clean or whatever tab you were using last time.

MagicTools License Key

You will need to obtain a MagicTools™ License Key and store it in the provided setting box in order to use the MagicTools software. Your organization only needs one currently active License Key and it may be used by any authorized users to manage your organization’s PI data. (see End User License Agreement)

License Keys look like this: 1A3B-C3D5-3E5F-4A6B 

You should have received a License Key in the order confirmation email sent to you by Believable Magic after you paid for a software license. 

If your organization purchased a software license but can’t find your License Key:

  1. The registered owner of the License Key must visit the My Account page and log in. You can recover your password if you forgot it (or you never knew you had a password).
  2. Click on Orders or recent orders
  3. Find your most recent order for MagicTools – for PI and click View
  4. Your License Key will be displayed to you

Copy and paste your License Key into the Setup tab where it says MagicTools™ License Key and click Validate. This will make a call to the believablemagic.com site to verify that your License Key is currently active. The outcome will be displayed below the License Key along with the expiration date.

  • If your License Key has expired, your organization will need to purchase a new License Key or work through your license administrator to extend the expiration date of your existing License Key. MagicTools will not function with an expired License Key.
  • If for some reason the believablemagic.com site is unavailable to check whether your License Key is active, MagicTools will still work for you — assuming the problem is with the License checking process and not with your Internet connection.

Predictive Index Settings

API Key

You will need to obtain a Predictive Index API Key and put it into the provided setting box in order to use MagicTools to read any of your PI data and/or make any changes to it.

API Keys look like this: 20078DE4-562E-4CEC-B3C9-B314E15438DA

You can obtain one by following these steps:

  1. Activate API Access to PI – Contact Predictive Index Support and ask them “Please ensure that API Access is turned on for our PI Account”. If your account does not have API Access turned on, any API Key you generate will not work.
  2. Choose or Create a PI User to Own the API Key – Keep in mind that you can only do with MagicTools as much as the PI user who owns the API Key is authorized to do. When deciding which User should own the API Key you’ll use with MagicTools, consider the following:
    1. It may be best to use your own User account to generate your API Key if you want all actions you take with MagicTools to be attributed to you. You won’t be able to tell the difference between actions you take while logged in directly to PI and those taken through MagicTools.
    2. It may be best to create a new User that you intend to use only with MagicTools so that you can tell the difference between actions you take while signed into the PI software directly and those taken via the PI API and MagicTools. For example, you might use “MagicTools” as the last name or Job Title for the user.
    3. If the API Key belongs to an Account Owner or Account Admin user, MagicTools will have access to read and change all person and assessment data in your PI instance.
    4. If the API Key belongs to a Power User, User, or Read-Only user who has access to only some of the person and assessment data, MagicTools will only be able to read or modify the permission-controlled set of person and assessment data available to that user.
  3. Generate an API Key for that User – Follow the instructions in the following PI Support site to generate your own API Key from within the PI Software’s Administration > User Management area: How to Generate an API Key
Using Cognitive Assessments

If your organization is using the PI Cognitive Assessment, be sure this box is checked. When checked, MagicTools will try to respect any Cognitive Assessment data when deciding whether Person data can be archived as part of the Clean processes.

If your organization is not using the PI Cognitive Assessment, be sure to un-check this box. Doing so will simplify the logic used by MagicTools and shorten the amount of time it takes to perform Clean tasks.

Processing Output Location

Select a folder into which you want MagicTools to place output files generated by any process you might run. For example, you might choose a sub-folder within your Documents or your Downloads folder.

In the case of Clean and Sync actions, log files containing all the proposed actions or actual actions are stored in this folder.

In the case of Export actions, your exported files will be placed into this folder.

Open Output Location – this link will open your selected Output Location in a system file explorer window so you can easily find the files you have generated during processing.

User Settings Location

This display-only information tells you where MagicTools is storing the settings you enter or select. These settings are stored in a file named “user.config”.

  • If you remove or modify the user.config file, it will affect the saved settings of MagicTools.
  • If you damage this file or it becomes unusable, you can safely delete it.
  • If you delete your user.config file, you will simply have to repeat the Setup steps to store your License Key and API Key. MagicTools will create a new user.config file if one doesn’t already exist.

Open Settings Location – this link will open the folder containing your user.config file in a system file explorer window in case you wish to view, edit, or remove your saved settings for some reason. 

Installing MagicTools – for PI

  1. Download the installer – When your organization purchased MagicTools, the buyer was sent an email message with a download link. Follow that link and download the executable installer program MagicToolsforPISetup.exe.
    • If your organization is licensed already, you may obtain the installer from a co-worker who already downloaded it. Any authorized users who manage your organization’s PI data may install MagicTools.
    • If you need to re-locate the download link, log into the My Account page and visit the Downloads sub-page where you will find a download link.
    • You can recover your password if you forgot it (or you never knew you had a password).
  2. Grant permission – Your browser may show you warnings when you try to download MagicTools:
    • You are downloading an executable program that can make changes to your system. This is normal. Click on options such as “Keep” or “Allow” before your browser will complete the download.
    • MagicTools is not a frequently downloaded program. This is normal for new software like MagicTools. Click “See more” and allow the download.
  3. Run the installer – locate the MagicToolsforPISetup.exe file in the location you downloaded it and activate it (click or double-click on it).
  4. Antivirus warnings – You might see an error or warning pop up if you have certain antivirus programs running. For example, Avast is known to pop up a “ShellExecuteEx failed” message which is a false alarm. Usually, this type of error goes away after a few seconds and the installer begins to run.
  5. Windows Defender warnings – You may see security warnings from Windows or Windows Defender letting you know the software is from an unrecognized source. Even though our installer is signed using an industry-standard code signing certificate issued to Believable Magic by USERTrust RSA Certification Authority, this warning will appear until enough people have installed it and it is recognized as safe. The warning looks like this:

    Click on the “More info” link, and you will see this:

    Click on “Run anyway”.
  6. Grant Permission – Windows will ask if you really want to install the program and you should allow it.
  7. Follow Setup Steps – you will see this setup window:

    Review the agreement, click “I accept the agreement”, and click “Next”.
    After continuing through a few more setup screens, you will arrive here:

    Click “Finish” and the setup window will disappear.
  8. Launch “MagicTools – for PI” – click the Windows menu and you should see it at the top of the list, like this:

    If you don’t see it at the top of the list, scroll down to the “M” section, or start typing “MagicTools” and you should see it.

Once you have the MagicTools software running, you should configure your software via the Setup tab.

Data included in Export People and Assessments

The following 89 data columns are included in the MagicTools – for PI output when using Export Persons and their Assessment data to CSV

  1. LastName
  2. FirstName
  3. MiddleName
  4. Email
  5. PersonType – Unknown, Candidate, Employee, Former Employee, Other
  6. ExternalPersonId – contains a value from an external system
  7. AssessmentUserId – – internal PI identifier assigned for each person
  8. SortName – field used for sorting by name
  9. SortDate – field used for sorting by date
  10. FolderId – PI folder id
  11. FolderPath – PI folder path
  12. UserId – PI user identifier, if present
  13. PersonCreatedTime
  14. Impression – rating of level of interest in a Candidate
  15. AssessmentInfo.LatestAssessmentCompletedDate
  16. AssessmentInfo.LatestAssessmentEmailSentDate
  17. ReferencePattern.PatternName
  18. ReferencePattern.BadgeUrl
  19. ReferencePattern.PatternNumber
  20. Behavioral.Assessment.Id
  21. Behavioral.Assessment.SentDate
  22. Behavioral.Assessment.CompletedDate
  23. Behavioral.Assessment.State – 10 = sent, 40 = complete, 50 = expired
  24. Behavioral.Assessment.AdministeredBy
  25. Behavioral.Assessment.AdministeredByPersonId – internal PI identifier
  26. Behavioral.Assessment.ScoreId
  27. Behavioral.OriginalAssessment.Id – internal PI identifier
  28. Behavioral.OriginalAssessment.ReferencePatternNumber
  29. Behavioral.OriginalAssessment.ReferencePatternName
  30. Behavioral.PendingAssessment.Id – internal PI identifier
  31. Behavioral.PendingAssessment.SendDate
  32. Behavioral.PendingAssessment.AdministeredBy
  33. Behavioral.PendingAssessment.AdministeredByPersonId – internal PI identifier
  34. Job.Name
  35. Job.FitScore.Combined
  36. Job.FitScore.Behavioral
  37. Job.FitScore.Cognitive
  38. Job.CognitiveTarget
  39. Job.JobId – internal PI identifier
  40. Job.LastModifiedDate
  41. Job.ModifiedByPersonId – internal PI identifier
  42. Cognitive.Assessment.Id – internal PI identifier
  43. Cognitive.Assessment.Score
  44. Cognitive.Assessment.CompletedDateTime
  45. Cognitive.Assessment.SentDate
  46. Cognitive.Assessment.State
  47. Cognitive.Assessment.AdministeredBy
  48. Cognitive.Assessment.AdministeredByPersonId – internal PI identifier
  49. Cognitive.PendingAssessment.Id
  50. Cognitive.PendingAssessment.SentDate
  51. Cognitive.PendingAssessment.AdministeredBy
  52. Cognitive.PendingAssessment.AdministeredByPersonId – internal PI identifier
  53. ReferencePattern.ASigma
  54. ReferencePattern.BSigma
  55. ReferencePattern.CSigma
  56. ReferencePattern.DSigma
  57. Behavioral.Assessment.Score.Self.ASigma
  58. Behavioral.Assessment.Score.Self.BSigma
  59. Behavioral.Assessment.Score.Self.CSigma
  60. Behavioral.Assessment.Score.Self.DSigma
  61. Behavioral.Assessment.Score.Self.ESigma
  62. Behavioral.Assessment.Score.Self.MScore
  63. Behavioral.Assessment.Score.SelfConcept.ASigma
  64. Behavioral.Assessment.Score.SelfConcept.BSigma
  65. Behavioral.Assessment.Score.SelfConcept.CSigma
  66. Behavioral.Assessment.Score.SelfConcept.DSigma
  67. Behavioral.Assessment.Score.SelfConcept.MScore
  68. Behavioral.Assessment.Score.Synthesis.ASigma
  69. Behavioral.Assessment.Score.Synthesis.BSigma
  70. Behavioral.Assessment.Score.Synthesis.CSigma
  71. Behavioral.Assessment.Score.Synthesis.DSigma
  72. Behavioral.Assessment.Score.Synthesis.ESigma
  73. Behavioral.Assessment.Score.Synthesis.MScore
  74. Behavioral.Assessment.ScoreAlt.Self.ASigma
  75. Behavioral.Assessment.ScoreAlt.Self.BSigma
  76. Behavioral.Assessment.ScoreAlt.Self.CSigma
  77. Behavioral.Assessment.ScoreAlt.Self.DSigma
  78. Behavioral.Assessment.ScoreAlt.Self.ESigma
  79. Behavioral.Assessment.ScoreAlt.Self.MScore
  80. Job.BehavioralTarget.ASigma
  81. Job.BehavioralTarget.BSigma
  82. Job.BehavioralTarget.CSigma
  83. Job.BehavioralTarget.DSigma
  84. Job.BehavioralTarget.ASigmaRangeLow
  85. Job.BehavioralTarget.ASigmaRangeHigh
  86. Job.BehavioralTarget.BSigmaRangeLow
  87. Job.BehavioralTarget.BSigmaRangeHigh
  88. Job.BehavioralTarget.CSigmaRangeLow
  89. Job.BehavioralTarget.CSigmaRangeHigh

Do I need MagicTools – for PI?

Your organization can benefit from MagicTools – for PI if any of the following 16 situations apply to you:

PI Data is not clean

  • Expired assessments – some PI persons have only expired assessment invitations
  • Duplicate persons – the same email address belongs to more than one PI person
  • Duplicate assessments – a person has more than one completed Behavioral Assessment
  • Invite by Link – you are using the Invite by Link feature which leads to duplication whenever a person goes through your process more than once

PI Data is not current

  • Wrong Person Type – Some employees are still identified as persons of type Candidate or Unknown, or former employees are still identified as persons of type Employee
  • Wrong Email – Employees have Candidate email addresses instead of employee email addresses
  • Domain Change – Employees have email addresses belonging to the old domain name used by your company, but due to a merger or domain name change you need to update them all at one time
  • Folder Changes – People are organized into PI Folders that no longer match your needs for organization or permission management
  • Job Mess – People are assigned to PI Jobs that are no longer accurate or useful to you
  • New Job Targets – You have started using the PI Job Target feature but many of your current employees have not been assigned to their correct PI Job
  • Too Much Manual Work – You wish to make updates to many persons in your PI data at one time rather than manually editing one item at a time

PI data is not connectable

  • Employees have an External Person ID belonging to your current or past Applicant Tracking / Recruiting system and you wish to replace it with one from your Human Capital / Human Resources software instead
  • You wish to upload Organizational Structure data into PI, but many of your Employees in PI do not have a correct Employee ID (External Person ID) which interferes with a successful upload
  • People have the wrong email address so that it doesn’t match what is in an external system that relies on email match (such as the PI Slack App)

PI data needed elsewhere

  • You wish to analyze patterns in your PI data using an external tool
  • PI data download feature doesn’t give you all of the fields you want