Configuring a User Preferences Provider App

by Christina Moore Updated Jul 21, 2020

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 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_user

Additionally, 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 = 'jane.doe@onit.com' | email_to_user | user_preferences_for_user %}{{my_user.approval_authority}}
Previous Article Configuring the Out of Office/Delegate Feature
Next Article Assigning Users/Groups to Suites using a Group Preferences App

© 2020 Onit, Inc.

docs.onit.com contains proprietary and confidential information owned by Onit, Inc. that is subject to copyright. Onit presents it exclusively to you for your sole use in conjunction with using Onit products. No portion of the materials contained herein may be used for any other purpose. No portion of the materials contained herein may be shared with third parties or reproduced in any form.