Onboarding Integration - Overview
This guide will help you configure the onboarding integration between Firstbase and Microsoft Entra ID. Once set up, Firstbase will automatically create an employee record when you create one in Microsoft Entra ID.
Note: Prior to setting up your integration, please ensure you have admin access and connect your account to Microsoft Entra ID if you haven’t done so by following these steps.
1. When does the onboarding integration run?
The Onboarding Integration runs once a day every 24 hours. It’ll run each day at the same time you start the onboarding workflow the first time. It may take 1-2 hours to run depending on the amount of employees in your system.
The Onboarding integration triggers based on the start date being in the future, and the employee not being present in Firstbase already.
2. How does the onboarding integration work?
The Onboarding integration will onboard certain users with or without a package based on your configuration settings.
There’s two configuration settings you can add as part of your onboarding integration:
- Package Mapping Rules - Package Mapping Rules allow you to automatically assign a package to a given employee at the time of creation. For example, if you'd want an employee’s in the Marketing department to automatically be assigned a marketing package.
- Customization Options - Customization Options allow you to skip/include only certain employees. For example, if you want to only create employees if their country is SG (Singapore) and their Employment Status is Full-Time.
3. How do I set the onboarding integration up?
1. Visit your Microsoft Entra ID Integrations page
2. Configure your "Onboarding Integration" (Optional)
The "Onboarding Integration" can be configured using two optional steps:
-
Create Package Mapping Rules - This step allows you to automatically assign a user to a package when creating them based on some criteria. For example, assign the Marketing package to all my Marketing users.
- See section here for detailed instructions on how to configure this.
-
Customize your Integration - This step allows you to exclude / include certain employees only when the integration runs.
- See section here for detailed instructions on how to configure this
3. Start your integration
Simply click on the “Start” button under on the Update User and you should be ready to go.
4. How can I automatically assign packages when onboarding?
When creating employees, you can follow these steps to automatically assign packages to users:
1. Open up the "Onboard User" flow within your Microsoft Entra ID Integration page
2. Click on "Edit Package Mappings"
In this step, you can choose how you want to assign packages to each of your employees through the onboarding integration. The following screen will open up:
Click on "Add package mapping rule", which will create a new rule that you can customize with different variables.
In general, you can map packages using the six available operators:
-
= Allows for a unique value.
- Example: "DEPARTMENT" = "Engineering"
-
≠ Allows for a unique value.
- Example: "DEPARTMENT" ≠ "Engineering"
-
IN - Allows for comma separated values.
- Example: "DEPARTMENT" IN "Engineering"
-
NOT IN - Allows for comma separated values
- "Employment Type" NOT IN "Engineering"
-
LIKE - Allows for comma separated values. Useful when you have small different variations for a given field. Like Sales - Contractor; Engineering - Contract; Operations - Contractor...
- Example: "Employment Type" LIKE "Contractor"
-
NOT LIKE - Allows for comma separated values. Useful when you have small different variations for a given field. Like Sales - Contractor; Engineering - Contract; Operations - Contractor...
- Example: "Employment Type" NOT LIKE "Contractor"
All conditions are AND conditions, meaning we'll consider all when assigning a package. There's no OR conditions today.
There's several integration fields you can use when customizing your package mapping using above operators. They include:
| Integration Field | Examples |
|---|---|
| Country |
UK, SG Note: Must follow standard standard 2 character ISO country codes. More info here. |
| Group Type |
This can be one of two values available in your Microsoft Entra ID account. You must specify which one you are using: Department or Division. |
| Group Name | Marketing, Engineering, Product, Operations, etc. |
| Employment Type | Part-Time, Full-Time |
|
Status |
Active, Inactive |
| Custom 1, 2, 3 |
We are able to use additional custom fields that you've built in your Microsoft Entra ID instance in addition to above. However, this needs to be mapped internally. Contact your CSM to learn more. |
Let's go through some examples based on possible use cases:
-
I'd like to assign a "Product Marketing Package" to all employees in my "Marketing" Department.
For this option, you'll need to configure your package mapping rules the following way:
- Group Type would = Department
- Group Name would = Marketing
- Package would be set to "Product Marketing"
-
I'd like to assign a "Customer Success Package" to all employees in my "Customer Success" Department, that are also based in US and UK.
For this option, you'll need to configure your package mapping rules the following way:
- Group Type would = Department
- Group Name would = Customer Success
- Country would be US or UK
- Package would be set to "Customer Success"
Note: When setting up country values please follow standard standard 2 character ISO country codes. More info here -> https://www.iban.com/country-codes.
3. Save your Package Mapping settings
You can add multiple conditions and package mapping rules and once everything is set up, click on "Save changes" and a notification pop up will appear as a confirmation.
5. How do I exclude/include certain employees from being onboarded via the onboarding integration?
You can specify within the integration if you only want to create certain employees in Firstbase if they are based in certain countries or if they have a specific employment type, for example. To do so, follow these steps:
1. Open up the "Onboard User" flow within your Microsoft Entra ID Integration page
2. Click on "Edit Configuration"
The following modal will open up. Choose "Add row"
3. Set up your configuration options:
Here, you can choose the fields you want to use to exclude/include only certain employees when the integration runs.
There’s four types of operators available: (1) = and (2) ≠ allow for one field, while (3) IN, (4) NOT IN allow for comma separated fields.
Let's go through some examples:
-
I'd like to only create employees based in Singapore and UK
For this option, you'll need to configure your customization settings the following way:
- Country IN SG, UK
Note: When setting up country values please follow standard standard 2 character ISO country codes. More info here -> https://www.iban.com/country-codes.
-
I'd like to only create employees if their employment type is full-time
For this option, you'll need to configure your customization options the following way:
- Employment Type = Full-Time
Following the same process as mapping rules, you can set up different integration fields, attach an operator, and provide a value to it, you can also add multiple rows for different options.
4. Save your customization options
Once everything is done, click on "Save changes", and a confirmation pop-up will appear. Then click on the “Start” button and we'll automatically onboard all users in your report in Firstbase every day! 🚀
6. I need to use a custom field, how can I approach this?
See FAQ here on using a custom field for your package mapping or customization options.