You may have different types of users who should see other information and Apps in Onit. For instance, you may want to restrict users in your Finance department to only seeing Timekeepers, Vendors, and Matters Apps. In contrast, users in the Intellectual Property department should also see the Patents and Contacts Apps.
With a Suite and a User Profiles App configured for your environment, you can add a Group Preferences App to control which page serves as a group of users' home pages and what navigation items they can access in the navigation menu.
Before We Start ...
This tutorial will assume you understand the following concepts:
- Building Your First App
- Supporting Workflow and Suites with a User Profiles App
- Creating an Action
- Creating a Business Rule
This tutorial will also assume you have configured a Suite for your environment. However, instructions for setting up a Suite are outside the scope of this tutorial.
Let's Get Started!
1. Create a new app named Group Preferences
You'll need to create a stand-alone app, which is the only job to keep users organized in user groups.
This app must be named Group Preferences.
2. Relate the Group Preferences app to the User Profiles app
Add a parent-child relationship between your Group Preferences app and your User Profiles app, where the Group Preferences app is the parent app.
Select the Don't render panel for this Field in your Group Preferences app.
See our Creating a Parent-Child Relationship tutorial for help creating this relationship.
3. Add Fields to the Group Preferences app
Your Group Preferences app must have the following required Fields:
| Field Name | Field Label | Field Type | Target App |
|---|---|---|---|
| requester_name | Name | Text | |
| requester_email | |||
| name | Group Name | Text | |
| default_suite_name | Default Suite Name | Text | |
| default_navigation_item | Default Navigation Item | Text | |
| suite_navigation_items | Suite Navigation Items | Text | |
| users | Users | HasMany | User Profiles |
4. Create a transaction for each group
Now that your Group Preferences app is configured, you'll need to create a transaction in this app for each group of users that needs a different homepage and navigation menu configuration.
In our example, we'll start by creating a transaction for a group of users in our company's Finance Department. Create a transaction with the following value types:
- Group Name: The name you want to give the group. In our case, that will be the "Finance Department."
- Default Suite Name: Provide the name of the Suite this group should be in when they access the Onit domain. In our case, we'll say we have a Suite we created specifically for our Finance Department
- Default Navigation Item: Provide the name of the Navigation Item you want this group of users to land on when they enter the Suite. For our use case, we'll say we have a Navigation Item configured in our Finances Suite named "Finance User Home."
- Suite Navigation Items: This is where you'll provide a JSON array that will determine which Navigation Items of the Suite your group of users will be able to see in their Navigation Menu. The JSON array must be in the following format:
{"Default Suite Name":["Navigation Item 1","Navigation Item 2","Navigation Item 3"]} In our example, our Finance Department users might have a Suite Navigation Items value of:
{"Finances":["Finance User Home","split","Matters","Invoices","Tasks"]}It is very important that this JSON is correctly formatted and only includes values for Navigation Items that already exist in your Suite. Ensure that:
- The JSON format shown above is followed.
- The quotation marks are straight quotes. Some text editors automatically turn your quote marks into "smart" or "curly" quotes, breaking the JSON.
- Every Navigation Item listed is an existing Navigation Item in your Suite. The name (rather than the Display Name, if different) of the Navigation Item must be the same as the value used in the array.
Known issue: If there is an error in the JSON you provide here and you are using the new React UI, all pages in your environment will throw an error except for your Administration page. The only way to reaccess this transaction will be to navigate to your Administration page and turn off the enabled React Beta Features.
Our Group Preference transaction that we'll associate with any of the users in our company's Finance Department will look as follows then:
5. Add users to your group transaction
The last step is to provide your users with a Group Preference. You can manually go to each user's transaction in their User Profiles transaction and provide a value in the BelongsTo Field that points the user to one of the Group Preferences transactions you've created. Or, if you have a long list of user records in your User Profiles app that need a Group Preference set, you can alternatively create and use Bulk Actions to quickly set this Field's value.
6. Add Action to update children on transaction update
If you need to update your Group Preferences transactions, you should also trigger an update on their children and the related User Profiles transactions.
Add an Update Related Transaction(s) Action to your Group Preferences app to trigger an update on your children's transaction.
Tie this new Action to a Transaction Updated Business Rule to fire when the parent is updated.
All set!
Congratulations! You've now configured Group Preferences for your Suite. When users associated with a Group Preference transaction enter your Onit domain, they will receive the defined landing page and navigation menu.