After a transaction is created, it will have one or more Participants. These are the people who can view and manage the transaction. Additionally, you can define different Roles for each Participant. For example, you could assign a Business Approver Role to a participant who has been assigned specific tasks.
Onit provides App Builders with multiple ways to define precisely who the Participants should be for any transaction. For some apps, this is simple: If the Participants will always be the same people for each transaction, you can hardcode them into your app’s configuration. However, some apps’ transactions will conditionally need different participants assigned to them.
One way to conditionally add participants to transactions is to have your requester provide participant information in a Field on the Launch Page. Using a special naming convention for this Field (which we’ll cover in this tutorial), Onit will do a little magic to automatically add a participant to a specific Role using this information.
For example, your Contract Approval app may have a Role of Business Approver. When a requester creates a new transaction, you can ask them to select a Participant’s name from a Combo Field. Using the naming convention detailed below, the value for this Field will automatically be added as the Business Approver to the transaction.
In this tutorial, we’ll explain how to add Participants to a transaction using values in a specially named Field.
The configuration explained in this article works well for apps with basic rules for adding Participants. However, if your app has complex rules—for instance, many different users are eligible to become Participants, and Onit should decide which one to add based on complex conditions—the approach explained here probably isn’t appropriate. Instead, see Adding Participants from a Decision Table.
Before We Start ...
This tutorial will assume you understand the following concepts:
Let's Get Started!
In this tutorial, we’ll create a specially named Combo Field that will be used to add the Participant a requester selects as its value into a Business Approver Role.
1. Create a New Role
First, we'll create the Role under which we want our Participant to be added.
Browse to the Roles screen in the Wizard. Add a new Role and provide it with a Name. For this example, we’ll name our Role Business Approver.
Leave the Email property of this Role blank since we want our requester to provide this information themselves on the Launch Page using the Field we’re about to create in Step 2.
Lastly, select a Role Type. We’ll make our Role an Approver.
Don't forget to add your new Role to a Tab!
Need additional help configuring your Role? See Step 3: "Roles" in the Building Your First App tutorial.
2. Configure a New Field
Now, let’s create the specially named Field that we keep referring to.
Browse to the wizard’s Fields screen. Click Add to create a new Field.
Here’s the magic part! Name the Field using the following convention:
<role_name>_email
In our case, the Field should be named as follows:
business_approver_emailAdding a Field to your app whose name follows this convention, Onit essentially says, “Oh, you want me to use the email address in this Field to set this Role. No problem!” And that’s it; the rest just works like magic -- you don’t need any additional configuration.
Note that in Onit, you add Participants to Roles using email addresses (not names), so this will only work if the value for this Field is an email address.
Tip: Remember that a Field’s actual Name and display name (i.e., Label) can differ. As a result, you can name the Field business_approver_email but then set its display name to something more user-friendly.
Next, we need to set the Field’s Type. Technically, the Field’s Type can contain an email address. In most situations, you’ll want to use a Combo Field, which allows users to select the appropriate Participant from a dropdown list.
What’s especially helpful here is that Combo Fields allow you to display one value to users but then save a different value. That means that we can display a name and save an email address. Why is this helpful? Because displaying a list of email addresses in a dropdown list isn’t very user-friendly -- it’s much better to show a list of names.
To configure your Combo appropriately, first set the Field’s Type property to Combo. Next, in the Values property, enter each dropdown value using the following pattern:
<save_value>:<display_value>
Separate different values using a comma. For example:
[email protected]:John Smith, [email protected]:Rebecca Jones, [email protected]:Mike Garcia
In this example, the dropdown of values would look as follows:
If a user selects the first value in this dropdown, Onit stores [email protected] in the business_approver_email. Additionally, Onit would set John Smith as the transaction’s Business Approver when creating the transaction.
Tip: You’ll probably want to make this Field required since your app will heavily depend on its value not being blank.
Need additional help configuring a Field? See Step 5: "Fields" in Building Your First App.
You’re done configuring your app. Browse to the Wizard’s last screen and click Update to save your changes.
Test It Out
Nice work! You’ve just configured your app to add Participants from a Field value.
To test this out, create a new transaction and select a value from the business_approver_email Field. After creating the transaction, check to see if the user selected has been set as a Participant in the correct Role.
