Onboarding Tutorial

Requirements

Internal System
Target System to provision (e.g. Active Directory, Google Workspace, etc.)
User Data for questions, answers, and notifications.
Note
At a minimum, include a unique identifier such as username or employee ID, and contact information such as personal email and mobile phone number.

Set Up the Onboarding Table

Before we can configure the Onboarding profile, you need to configure the Onboarding table to store user data.

Click the Internal System. Under the Configuration tab, select the Onboarding table.
Expand the Internal system and select the Onboarding table. Go to the Columns tab.
Ensure the ID column is marked as a Key
Next, a relationship need to be created between the ExternalID column of the Onboarding table and a target system table. In this case, AD > Users. See Inter-system relations for more information.

Prepare User Data

You will need at least two filters to drive the onboarding process. One will insert user records into the Onboarding table, and the other will be used to look up an individual onboarding record.

Create a new filter and name it accordingly (e.g. Onboarding_Employee_Create). This filter should return active users who do not currently have an onboarding record.
Note
Include columns such as employee ID, personal phone number, personal email. These will be used later in a Mappings to create the onboarding records.
Create two additional script columns within this filter: onboardExpires and secureID.
1. onboardExpires - Generates a date object for the onboarding profile to use as an expiration date. Adjust the number of days you want the profile to be accessible by changing the “7” to the number of days needed. This will prevent an onboarding record from being accessible for all time, which would create a security risk.
```
let currentDate = new Date();

return currentDate.setDate(currentDate.getDate() + 7);
```
2. secureID - Generates the unique secure ID that will be used for each user's onboarding profile. This ID will be used as part of a link sent to the user so that they may quickly and easily access their onboarding record.
Create a new filter and name it Onboarding_Employee_Lookup. This will be used to generate the variables for the answers to your security questions and the mapping in your Onboarding Profile. This will be a parameter-based filter for the ExternalID in the onboarding table.
Important
This filter must also return the unique identifier of the user's target system account, such as the objectGUID field for Active Directory. This will allow NIM to enable and reset the password of the target account later during the onboarding process.

Provision Onboarding Records

The filter data we created now needs to be used to create onboarding records

Create a new mapping called Onboarding_Employee_Create.
In the Filter dropdown, select the Onboarding_Employee_Create filter you created previously. Map all fields accordingly, using the screenshot below as an example. Some fields, such as Profile, MailAddressLabel and SMSPhoneNumberLabel should be set manually to a constant value.
Important
The Profile field value will need to match the name of an Onboarding Profile, which we will create in our next steps. In this example, we are calling it EmployeeOnboarding.
Save the mapping.
Create a new Job.
Under the Configuration tab, add a new CRUD task and select the mapping you just created.
Optional: You may choose to evaluate and run the job at this time and create all of the onboarding records. You may also add the job to a task schedule and run it at a recurring time.

Create Onboarding Profile

The onboarding profile contains the settings and configurations that tie onboarding each component together and define how they interact.

Go to Configuration > Onboarding.
Click Add to create a new onboarding profile. Provide it the same name as the Profile field in the mapping you created previously.
In the top section of the profile, configure the dropdown fields accordingly:
1. Under Onboarding app, select Onboarding
2. Under Question-answer filter, select the Onboarding_Employee_Lookup filter you created earlier.
3. Select message for the remaining two drop downs on the right.
In the Onboarding Profile Forms section, click the Add button five times to add five form entries (one for each screen of the onboarding process).
For each entry, use the dropdown menus to set the Form Name, Form Function, Form Variable, and Onboard Variable fields. On the password form entry, select the Execute and Notification options. Your section should look like the screenshot below.
Optional: You may select a form and customize the text of that form in the Form Contents section at the bottom of the screen. This is commonly done when the lookup criteria for an onboarding record is something other than an employee ID (e.g., username or student ID).
Navigate to the Action Variables tab. Click the button next to any field you wish to reference during the onboarding process. This will auto-generate a variable name for that field. For Active Directory, we recommend the following:
1. objectGUID - This will be used by NIM to target their account and complete the onboarding process.
2. sAMAccountName - This will be used for logging and notifications.
3. displayName - This will also be used for logging and notifications.
Navigate to the Onboarding Actions tab. Onboarding actions are similar to mappings for filters in their function.
1. Add a new action by selecting the Add at the top right.
2. Select a system, such as Active Directory.
3. Select the UserUpdate function, or the target system's equivalent.
4. Map what variables you’ve created in the configuration and action variables pages to their corresponding AD attribute. In this case, you will need the objectGUID, accountPassword, and enabled set to true to allow the user to claim their account.
5. Select Generate Notification Event if you want administrators to receive a notification after an account is claimed.
Save the onboarding profile.

Configure End-User Verification Email Notification

To confirm their identity, NIM will send end users a one-time passcode (OTP) token. During onboarding, users can choose to receive the code via email or SMS text message, depending on the methods listed in their onboarding profile. The following steps show you how to create a template and event to handle email notifications.

Navigate to Events > Templates.
Add a new template.
In the Notification Event dropdown, select onboarding-code-mail: EmployeeOnboarding.
In the To field, type or use the Append button to add the variable {var.event.data.voConfirmationCodeAddress}. This variable contains the address the end user selected to receive their OTP token.
Provide a suitable subject for the email.
In the body, provide a suitable message. Be sure to include the variable {var.event.data.voConfirmationCode}, which contains the OTP token for the end user.
Save the template.
Navigate to Events > Actions.
Add a new action. Set the Event Type to onboarding-code-email and select your onboarding profile name in the Event Name dropdown.
In the Template dropdown, select the name of the event template you created earlier.
Click Save.

Configure End-User Verification SMS Notification

Important

Sending SMS text messages requires an SMS license key to be installed. See this article for more information.

Navigate to Events > Templates.
Add a new template.
In the Notification Event dropdown, select onboarding-code-sms: EmployeeOnboarding.
In the Notification Type dropdown, select SMS.
In the To field, type or use the Append button to add the variable {var.event.data.voConfirmationCodeAddress}. This variable contains the phone number the end user selected to receive their OTP token.
In the Message field, provide a short but suitable message. Be sure to include the variable {var.event.data.voConfirmationCode}, which contains the OTP token for the end user.
Save the template.
Navigate to Events > Actions.
Add a new action. Set the Event Type to onboarding-code-sms and select your onboarding profile name in the Event Name dropdown.
In the Template dropdown, select the name of the event template you created earlier.
Click Save.

Optional: Create End-User Welcome Email

When an onboarding record is provisioned, NIM can send the end user an email that welcomes them to the organization and provides them a personalized link to the onboarding process. This link uses the secureID value that was generated for their record and bypasses the need for the user to verify their identity with an OTP token.

Navigate to Events > Templates.
Add a new template.
In the Notification Event dropdown, select mapping: Onboarding_Employee_Create.
In the To field, type or use the Append button to add the variable {var.event.argument.MailAddress1} (or whichever field you mapped the personal email address to).
Provide a suitable subject for the email.
In the body, provide a suitable message. Be sure to include a URL or hyperlink constructed of the following variables, which the user can visit to claim their account and bypass the need for identity verification: {var.system.ExternalHostUrl}/onboarding/{var.event.argument.Profile}/{var.event.argument.SecureID}
Save the template.
Navigate to Events > Actions.
Add a new action. Set the Event Type to mapping and select the mapping that provisions your onboarding records in the Event Name dropdown.
In the Template dropdown, select the name of the event template you created earlier.
Click Save.