HR Data Connector is one of the most valuable features of Insider Risk Management.
It allows you to monitor user activities when the users are considered a potential risk to the organization.
For example, if the user is being terminated, or the user gave a resignation notice, they might be departing not only with grudges but also with the company’s secrets. Additionally, if the user received a bad performance review or was demoted, it might be a strong risk indicator as well, and the activities of such users should be monitored.
Even when employees excel at their jobs and receive promotions, it could be worth monitoring their activities: if the promotion grants access to sensitive information or top secrets, you need to ensure that the motivation behind the career advancement was indeed to contribute to the company, and not to rise to the top in order to commit data exfiltration on behalf of another entity, whether it is for another government or corporation.
In this article, I am going to show you how to create an HR Data Connector.
In the next article, I am going to show you how you can quickly create a Power Platform Canvas App for your HR Department so that HR officers can easily enter new information. Additionally, I will show you how to automate the HR Data Connector so that M365 is updated right away.
But first, let’s look at the basics of the HR Data Connector. Microsoft made it very simple.
Data is saved in a comma-delimited .CSV file.
The file supports specific HR scenarios, such as resignation or termination. You can combine all HR events into a single file if you want, or have separate .CSV files for each scenario.
The reason you might want to have different CSV files is if you have different HR Teams or Systems that deal with different HR actions (for instance, if only one system or team deals with employment terminations).
You will then use a PowerShell script that is provided by Microsoft to upload the CSV file to M365. The Insider Risk Management will use this data to generate risk indicators.
Here is a table that lists which IRM Policy templates can use HR Data Connector Scenarios:
Policy template | HR data type |
Data theft by departing users | Employee resignations |
Data leaks by risky users | Job level changes, Performance reviews, Performance improvement plans |
Security policy violations by departing users | Employee resignations |
Security policy violations by risky users | Job level changes, Performance reviews, Performance improvement plans |
Healthcare policy | Employee profile |
Prerequisites
You must have a Data Connector Admin role to implement the HR Data Connector.
If you are a Compliance Administrator, you already have that role.
But for personnel that will be taking care of the HR Data Connector it's better to create a custom role group with the Data Connector Admin role to adhere to the principle of least privilege.
Register App
You need to create an Entra ID App Registration for your HR Data Connector.
Login to Microsoft Entra Admin Center
Expand the Applications section and click “App registrations”.
Click “+ New registration” link in the app registrations.
Enter Name, in my case it’s IRM HR Data Connector
Select supported account type
Click “Register”
7. Note and save the Application (client) ID when your App Registration is created. You will be using it in two of the next steps.
8. Next, go to the "Certificates & secrets".
9. Click "+ New Client Secret" 10. In the "Add a client secret" Panel add Description and Expiry.
11. Click "Add" button
12. Copy the value of your secret - you will be using it in the script when uploading the data for your Data Connector.
CSV Data File
Now we are going to create a CSV file for our connector.
Microsoft provides sample entries on its website:
https://learn.microsoft.com/en-us/purview/import-hr-data?tabs=microsoft-purview-portal#csv-file-for-employee-resignation-data
Employee Resignation Data:
Job Level Changes Data:
Performance Review Data:
Performance Improvement Plan Data:
For this example, we are going to use one single file. Let’s consolidate all these data into one CSV file.
Note that the first column in this file is the HRScenario column, which will have the following values:
Resignation
Job level change
Performance review
Performance improvement plan
If you look at the sample file above, you will notice that some columns apply only to specific HR scenarios. Additionally, while some columns are mandatory for certain scenarios, others are not. Empty values will be ignored unless they are mandatory. If mandatory values are missing, the entry will be skipped during the data upload process, and you will receive an error. Missing data for non-mandatory values will produce a warning message.
Below are the screenshots of the Canvas App that I will cover in the next posting. They will help you quickly see which values are used by specific HR scenarios – they will be either enabled or disabled. The red asterisk marks mandatory fields for the HR scenario.
Note on the Date Format
When entering dates into your CSV file for the CSV file, it is crucial to use the ISO 8601 format to ensure consistency and proper parsing.
In PowerShell, you can easily convert dates to this format using the following command:
Get-Date -Format 'o'
For example, to set a resignation date as yesterday and a last working date as two weeks from the resignation date, you can use the following PowerShell commands:
$resignationDate = (Get-Date).AddDays(-1) | Get-Date -Format 'o'
$lastWorkingDate = (Get-Date).AddDays(13) | Get-Date -Format 'o'
Creating the HR Data Connector
In MS Purview, go to ‘Data connectors’.
Scroll down to find HR Data Connector
Click to select
Click the ‘Add connector’ button
Provide App ID (this is the App Registration ID that you created in Microsoft Entra in the previous step)
Enter a unique name for your HR Data Connector
Select HR Scenarios
8. Choose '.csv file - Comma delimited' format of the file
9. Choose 'Upload a sample file' option
10. "Upload sample file" button will be activated. Click to upload your .CSV file. The actual values in the file don't matter at this point. The objective is to have all of the HR Scenarios and to map the columns.
11. After the file successfully uploaded, click Next
12. In the next screen you will be mapping the scenarios to the columns. The columns in your CSV file can have any names you want, as long as the are properly mapped in this step:
Here are some mapped columns:
13. Review and finish creation of your connector:
14. At the end of the Connector Creation Wizard, you will be provided with a jobId, which you will be using in the next step.
Uploading the CSV File
You will now need to download the PowerShell script to upload your CSV file to M365. You can find the script at this URL.
Click Raw and copy the script or use this link to get raw script.
Save the file as HRConnector.ps1 and run it with the following parameters:
.\HRConnector.ps1 -tenantId <tenantId> -appId <appId> -appSecret <appSecret> -jobId <jobId> -filePath '<filePath>'
The filePath is the path to your CSV file that you created.
AppID – the AppID that we created in MS Entra when we Registered the App.
JobId – the JobId was created when we set up the HR Data Connector in MS Purview.
The rest of the parameters are self-explanatory.
NOTE: The CSV must contain valid UPNs (User Principal Names), otherwise, the script will not run successfully.
ATTENTION: As of the writing of this article, the Microsoft example had two major errors in the example they posted in the article.
See the screenshot below and note that the Job Level Change Scenario has Resignation Date, but is missing Effective Date, which is a mandatory column for this Scenario. Your script will skip records if you use Microsoft's example.
When you run your script, it will run with warnings if it finds empty values for columns that are not mandatory. You can disregard those warnings as long as you don’t have any errors.
If the script finds errors in your CSV file, it will skip the entries that caused the error and will continue to the next entry (row in your CSV file).
Checking the Status of Your HR Data Connector
Here is how you can check the status of your HR Data Connector.
In MS Purview, go to ‘Data connectors’
In Data connectors, click on ‘My Connectors’
Select your HR Data Connector
In Properties, find the Admin Log File and click on the ‘Download log’ link
How Connector Data is updated
When you upload an additional CSV file to the HR Data Connector in Microsoft Purview Insider Risk Management (IRM), the data is cumulative. This means that each new upload adds to the existing data rather than replacing it.
For example, if you initially upload a CSV file containing data for 10 users, and then later upload another CSV file with data for 6 additional users, the system will now have data for 16 users in total. The new upload does not substitute the existing data; instead, it appends the new entries to the existing ones.
If you need to update information for users that were previously uploaded, you can include their updated details in the new CSV file, and it will be merged with the existing data. This allows for continuous data integration without the risk of losing previously uploaded information.
In the next articles, I am going to show you how to use Canvas App to add data to your CSV file and how to automate refreshing your HR Data Connector with new records. The solution will be more user friendly as you don’t expect HR officers to use PowerShell to run the scripts or even generate date in the format that connector expects.
Comments