After a transaction is created, it will have one or more Participants. These are the people that can view and manage the transaction. Additionally, you can define different Roles that any given Participant will play. For example, you could have a Business Approver Role, which would be assigned specific tasks to complete.
Onit provides App Builders with multiple ways to define exactly who the Participants should be for any given transaction. For some apps, this is simple; If the Participants will always be the same people for each transaction in your app, you can hardcode these users 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 into a specific Role using this information.
For example, maybe your Contract Approval app has a Role of Business Approver. When a requester creates a new transaction, you can ask them to select an 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 that have basic rules around adding Participants. If your app has complex rules -- for instance, there are lots of different users that are eligible to become Participants and Onit should decide which one to add based on a complex set of 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 that we want to our Participant to be added under.
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:
In our case, the Field should be named as follows:
By adding 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 value for this Field is an email address.
Tip: Remember that a Field’s actual Name and its display name (i.e. Label) can be different. 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 be anything that can contain an email address. That said, in most situations you’ll want to use a Combo Field, as that will allow 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:
Separate different values using a comma. For example:
email@example.com:John Smith, firstname.lastname@example.org:Rebecca Jones, email@example.com:Mike Garcia
In this example, the dropdown of values would look as follows:
If a user selected the first value in this dropdown, Onit would store firstname.lastname@example.org into the business_approver_email. Additionally, on creation of the transaction, Onit would set John Smith to be the transaction’s Business Approver.
Tip: You’ll probably want to make this Field required, since your app will be heavily dependent 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 the transaction has been created, check to see if the user selected has been set as a Participant into the correct Role.