Okta - Onboarding Integration

Onboarding Integration - Overview

This guide presents an overview of the Firstbase - Okta integration along with a detailed walkthrough of all configuration steps. Once set up, Firstbase will automatically create an employee record when you create one in Okta.

Note: Prior to setting up your integration, please ensure you have admin access and connect your account to Okta 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 whenever a new employee is created in OKTA, as long as the employee is not present in Firstbase already. 

2. How does the onboarding integration work?

The process will start running automatically at the same time you begin the flow each day. It usually takes about 2 hours to complete. Once it's finished, you'll see the results reflected in Firstbase.

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, you may want to assign a "Marketing Package" if an employee is part of the Marketing Department.
• Customization Options - Customization Options allow you to skip/include only certain employees. For example, you may want to only create employees if country is SG (Singapore) and their Employment Status is Full-Time.

The following information is used to map data between your Okta account and the Firstbase account. Some of it is only used if you set up customization logic like automatically assigning packages or skipping certain employees. 

Data Field	Okta Field Name	Mandatory
First Name	firstName	YES
Last Name	lastName	YES
Primary Email	email	YES
Secondary Email	secondEmail	YES
Country	countryCode	YES
Street 1	streetAddress	Only if using Automatic Orders; Should be the address for shipping the equipment
Street 2	streetAddress2	Only if using Automatic Orders;
City	city	Only if using Automatic Orders; Should be the address for shipping the equipment
Postal Code	zipCode	Only if using Automatic Orders; Should be the address for shipping the equipment
State	state	Only if using Automatic Orders; Should be the address for shipping the equipment
Group Type	This can be one of four fields in Okta. You can choose which of them you'd like to use when customizing your integration. Possible values include: Division, Department, Cost Center, or Organization.	Only if there's customization options needed
Group Name	Field Value for the chosen group type (e.g. Operations, Marketing etc.).	Only if there's customization options needed
Employment Type	employmentType (e.g. Part-time, full-time)	Only if there's customization options needed This must be set as a custom field in your Okta configuration to be used.
Employment Status	Status (e.g. Active, Pending, Inactive)	Only if there's customization options needed
Firstbase	firstbase	Only for filtering out certain employees outside the above options.  This must be set as a custom field in your Okta configuration to be used.
Phone Number	primaryPhone	YES
Start Date	Created At	YES; As Okta does not have a base attribute field for start date, we assign the "Created at" date.

 

3. How do I set up the onboarding integration?

1. Visit your Okta Integrations page

2. Configure your "Onboarding Integration" (Optional)

The "Onboarding Integration" can be configured using two optional steps. If these steps are NOT configured, then we will create in Firstbase any new employee you create in Okta that is not already present in Firstbase, and will not assign a package on creation, nor send these users an invite to Firstbase. 

The two optional configuration options include:

• 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

Click on the “Start” button under on the "Onboard User" flow and you should be ready to go.

 

4. How can I automatically assign packages to user through the onboarding integration?

When creating employees, you can follow these steps to automatically assign packages to users:

1. Open up the "Onboard User" flow within your Okta 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 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 four values available in your Okta account. You must specify which one you are using: Department, Division, Cost Center or Organization
Group Name	Marketing, Engineering, Product, Operations, etc.
Employment Type	Okta does not have a base attribute for employment type field. This must be configured as a custom field in your Okta instance and be named "employmentType".  Examples of values you may want to add under this "employmentType" field include Part-Time, Full-Time, Contractor, etc.
Status	Active, Inactive
Custom 1, 2, 3	We are able to use additional custom fields that you've built in your Okta 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: 

• Country would be US or UK
• Group Type would = Department
• Group Name would = Customer Success
• 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. For example, you may want to only create employees if they are based in certain countries or if they have a specific employment type. To do so, follow these steps:

1. Open up the "Onboard User" flow within your Okta 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 using the available operators. 

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 talk with a customer representative so that department gets mapped by Firstbase to one of the custom fields, prior confirmation by your customer representative you will then select a custom integration field and configure your customization settings the following way:

• Custom 2 = 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.