With a small amount of configuration, you can build out a simple App, called a User Preferences App, to contain a Record for each of the users in your system that includes details about them. User Preferences Apps are helpful when:
- Your business logic is dependent on attributes of your users. For instance, you may have an invoice approval workflow that determines which user should be added as an invoice approver based on that user’s approval authority.
- You are setting up a Suite in your environment. A User Preferences App is an essential component of a Suite configuration and is where landing pages and navigation within a Suite is determined for each user.
This tutorial will cover how to configure the User Preferences App and provide an example of how to build workflow off data in a user’s Record in this App.
Before We Start ...
This tutorial will assume you understand the following concepts:
Let's Get Started!
1. Create a new App
You'll need an app whose only job is to contain a Record for each of your users. Add a new App and name it User Preferences.
Note: You can name this App whatever you like but User Preferences and/or User Profiles is most common.
2. Configure User Preferences App Fields
Add the Fields below to your new App. These Fields names can be customized to your environment, for now we will use these names to keep things simple.
Note: The User Profiles App can now have a Field where a user can set their "Preferred Locale". This controls preferences around date and currency format. For example, if your Locale is in Germany, you'll see currency formatted like this: "1.005,50$" instead of this: "$1,005.50". To customize preferred locale you must upload this list of locales into your Onit environment.
| Field Name | Field Label | Field Type | Additional Configuration |
|---|---|---|---|
| requester_name | Requester Name | Text | |
| requester_email | Requester Email | ||
| name | User Email | Text | |
| user_name | User Name | Text | |
| default_suite_name |
Default Suite Name |
Text |
|
| default_navigation_item |
Default Navigation Item |
Text |
|
| suite_navigation_items |
Suite Navigation Items |
Text |
|
| preferred_locale |
Preferred Locale |
List Combo |
List: "Locales" Search Column: "name" Value Column: "key" |
You can also add any Fields that you'll need to track data about your users, such as their approval authority, what country they're working in, etc.
3. Configure a User Preference Provider
Head over to your User Preferences App's Advanced Designer page.
Select the User Preferences Providers node from the left-hand menu.
Click the Plus button to create a new User Preferences Provider.
Provide your new User Preferences Provider with a Name.
Next, select your new User Preferences App for the App property. Assign each Field created in the last step with the appropriate property.
Leave the Date Format property blank.
Select OK to save this configuration.
All set
That's all there is to setting up a basic User Preferences App.
Try adding a new user to your environment, either by adding them as a participant to a Record on a different App or by adding them through the corporation's Administration page. Afterward, check your User Preferences App and you'll see a new Record has been created for that user.
Building Workflow with User Attributes
You can now customize your User Preferences App to include the information necessary for building out your workflows and business logic.
For instance, you can add a Field to track a user's approval authority and can build a Condition to determine whether they should be assigned as an approver to an invoice based on the Field's value.
You'll need to use the following specific Liquid filter to find a user's attribute:
user_preferences_for_userAdditionally, your Liquid script must pass a user object to the filter. That is, you can use either current_user or, to filter for a specific email address, add the filter email_to_user.
So to find the value of a Field named approval_authority for the current user, you would use the following script:
{% assign my_user = current_user | user_preferences_for_user %}{{my_user.approval_authority}}To find the value of the same Field for a specific user's email address, the following script would be used instead:
{% assign my_user = '[email protected]' | email_to_user | user_preferences_for_user %}{{my_user.approval_authority}}