In most Onit environments, each user has two different (yet related) user objects:

1. Users: This object is visible (to Onit System Administrators) on an environment’s /admin page (as seen below). It provides the user with the ability to actually log into the environment and it tracks a minimal number of properties (e.g., the user’s name, email address, last sign in timestamp - it is not possible to add new custom properties to this object).

2. User Preferences Provider App: In most cases, an app named User Profiles is created in the environment and it is designated as a User Preferences Provider (as explained here). Each corporation user object (described in the bullet-point above) will have exactly one matching Record in the User Profiles app. Since User Profiles is an Onit App, you can customize it however you like. For example, you can add new Fields to “decorate” users with custom properties. In addition, you can fire Business Rules, Actions, Buttons and other workflow-related items on these Records. As a result, you can essentially treat users like you would any other business object from a workflow standpoint.

It’s important to understand how and when the above objects are created in Onit.

1. A corporation user object is created when any of the following events occur:
   • A new user is added as a Participant on any Record in the environment.
   • A System Administrator manually creates a user by clicking Add User on an environment’s /admin page.
   • A user successfully authenticates into Onit via SSO for the first time and the environment’s “auto create user” setting is enabled (this setting is described in more detail later in this tutorial).

1. A User Profile Record is created when any of the following events occur:
   • A new corporation user object is created (regardless of how this object is created). When the corporation user object is created, Onit automatically checks the environment for a User Preferences Provider App. If this App exists, Onit checks the App for a Record that has a name Field value that matches the corporation user object‘s email address. If no match is found, Onit automatically creates a new Record in this app.
   • A user, Onit Action, or API call creates the Record. In other words, since User Profiles is just an App, Records can be created in this environment just like any other app. This approach is often taken if the the user in question cannot log in via SSO (e.g., the client doesn’t use SSO internally and/or the user doesn’t work directly for the client).

If an environment has single sign-on (SSO) enabled, as mentioned above you can auto-create their user object when they SSO into Onit for the first time.

To enable this feature, browse to your environment's Administration page and open the Edit Corporation pane. Navigate to the Security tab and check Auto Create User.

Enabling this feature will ultimately create a new user Record in your User Preferences Provider App for each brand new SSO sign in. You can use this event (i.e., the creation of a new Record) as a trigger for automation, by firing Business Rules and Actions. For example, you could automatically add the user to a default group, send the user an email, start an approval process for the user, etc. Tips on how to build these types of automation are covered below.

When onboarding a new user, you may want to send the user through an approval workflow before activation. Approvers on this workflow might include the user's supervisor or anyone else who needs to approve a new hire. Once a user has been approved, they can be added as a Participant on their own User Profiles Record in order to customize their Onit preferences.

The following is an example of a new user approval process workflow:

1. A new user signs into the Onit environment through SSO.
2. A new user Record is created in the User Preferences Provider App.
3. The user is temporarily deactivated using the Activate or Deactivate User Action (explained below).
4. The user's supervisor is added as an approver on the Record.
5. Pre-approval actions are taken on the Record (e.g., assigning an employee number).
6. The new user is ultimately approved.
7. The new user is reactivated using the Activate or Deactivate User Action.
8. An onboarding email is sent to the user, welcome them to Onit.
9. The user is added as a Participant on their own Record.

It is recommended that you always automatically add each user as a Participant on their own User Profiles record. There are numerous benefits to doing so. For example, this ensures that the user will always have a corporation user object. In addition, this allows the user to customize some aspects of their own preferences, such as their phone number or enabling their out of office delegate.

To add a user as a Participant on their own User Profiles record, an Add Participant Action should be used and it should be configured as shown below.

The Emails property should evaluate to the user's email address. The user's name can optionally be included in angle brackets after the email – this is recommended but not required, the angle brackets will push the user’s full name into the corporation user’s object.

The Role property is a dropdown list of all Roles available in your App. It is recommended that you create a specific Role for the user on your User Preferences Provider App (e.g., User). Defining a Role will allow you to set Role level permissions for the user and help organize Phases in your user approval workflow.

Users that will not log in via SSO must authenticate via an email address and a password. Whenever a new Record is created in the User Profiles app for a brand new non-SSO user, you should configure a Conditional Compound Action (CCA) to generate a password reset token, and email the user, welcoming them to Onit. This email should also contain a link that allows the user to set up their Onit password.

In this situation, technically the user must reset their password in order to log in for the first time. Onit provides an Action that generates a password reset token named Create Reset Password Token. Once a token is created, via the Action, a Liquid filter named reset_password_url becomes available. Filtering the user’s email with reset_password_url will generate the user’s password reset URL. Therefore, it is necessary to fire the Create Reset Password Token Action before the Send Notification Action.

Below are examples of the Create Reset Password Token Action, Send Notification Action, and the CCA which fires both Actions:

Notice the Liquid in the Send Notification Action,

{% assign url ={{name}} | reset_password_url %}{{ 'Set your Onit password' | button_link: url }}

This Liquid uses the generated password reset token from the Action and the reset_password_url filter to create a password reset link.

Once a new user Record has been created in the User Profiles App, the related user can be automatically assigned to a Suite by associating them to a Group Preferences Record. This can be especially helpful if you want all automatically created users to default to a specific Suite.

To programmatically assign a user to a Suite, use a Find or Create Related Transaction Action in the User Profiles app. This Action should relate the User Profiles Record to the appropriate Group Preferences record, by way of setting the group_preferences Field. The example configuration shown below is configured to relate new (auto-created) users to the HTIU Group. Pay particular attention to the Params Liquid property. The r_users_id:{{id}} Liquid expression relates the user's Record via ID ( {{id}} ) to the appropriate Group Preferences Record (r_users_id).

As seen above, it’s important that the Relation Field Value property contain an if condition, not simply a hardcoded group name. The reason why is somewhat complicated, and it is related to the fact some User Profiles Records are created automatically while others are created manually.

Let’s consider two examples:

• Auto Creation: A user named Mike is automatically created in Onit when Mike logs in via SSO for the first time. As a result, Mike’s corporation user object is automatically created, which in turn creates Mike’s User Profiles record, which in turn triggers the Find or Create Related Transaction Action shown above. The Liquid in the Action checks to see if the User Profiles Record is already related to a parent Group Profiles record, and since it is not it relates the child Record to the parent Group Profiles record named HTIU Users.
• Manual Creation: A user named Sally is manually created by an Onit administrator creating a new Record in the User Profiles app. When creating this Record, the administrator populates the App’s Launch Page will various field values, such as the user’s email address, full name, and their group. For the group, the user selects a value from the group_preferences Field’s dropdown, which identifies which group they will belong to. In this situation, the Find or Create Related Transaction Action shown above will still fire, but we don’t want to overwrite the group manually selected by the Onit administrator that created the Record – the if condition ensures this won’t happen.

When a user leaves the office they can choose an out of office delegate to assume their Role(s) while they are gone. For more information on how to set this up, see our out of office delegate tutorial.