You can schedule the generation and distribution of email-based reports that contain Record data.
For instance, you could configure your Contract Administration app to send out a list of Records that are in Phase 1. Or, you could notify certain Roles about transactions that haven’t been worked on in over a week.
Reports can query for Records that match a Filter on a nightly basis and only send out a notification if one or more matches are found. Reports require very little maintenance but can play a critical role in your Apps’ success.
Before We Start...
This tutorial will assume you understand the following concepts:
Let's Get Started!
In this tutorial, we’ll configure a report that will run a Filter on a nightly basis for any Records in Phase 1. If matches are found, Onit will send a report containing details about each matched Record to the relevant users.
1. Create a Raw Transaction Filter
Begin by creating a Raw Transaction Filter for Records that match the criteria your report recipients need.
In our example, we want our Filter to evaluate whether a Record is in Phase 1 of our App. Our Raw Transaction Filter should look something like this:
Note: Need help creating a Raw Transaction Filter? See Creating Raw Filters.
2. Creating a Raw User Filter
In addition to evaluating which Records a report should contain, we’ll also need to evaluate which users it should be sent to.
Create a new Raw User Filter that matches the email address(es) for all of the users that should receive the report. In our example, we’ll say Mike Jones and Mary Stewart both care about Records expiring so our Raw User Filter will look as follows:
Note: If you need help writing a Raw User Filter, see the Raw User Filters section of Creating Raw Filters.
3. Configure a Send Report Action
Next, we need to create an Action to send our reports.
In the Actions node of your App's Advanced Designer, Add a new Send Report Action.
Provide a Name for the Action. Leave the To and CC properties for this Action blank since we'll be defining who should receive reports with our Raw User Filter when we build our Business Rule in Step 4 below.
Provide your Action with a Subject and a Body, both of which can contain Liquid.
While the subject is pretty straight-forward, you might need some help filling out the body. Our report’s Body needs to contain some Liquid that does the following:
- Determines how many Records match our Filter.
- Sorts the Records by some variable.
- Spits out some data from each Record, including HTML links to each one.
Below is a sample body:
{% if atoms.size != 0 %}
<p>The following contracts are in Phase 1:</p>
{% assign sorted_atoms = atoms | sort: "curr_state_name" %}
<table cellpadding="4">
<tr>
<th align='left'>Contract Name</th>
<th align='left'>Other Party</th>
</tr>
{% for atom in sorted_atoms %}
<tr>
<td><a href="https://contracts.onit.com/atoms/{ {atom.id }}/">{{atom.name}}</a></td>
<td>{{atom.other_party}}</td>
</tr>
{% endfor %}
</table>
{% endif %}This Body is taking care of the three requirements we listed above:
- The if statement checks to see if there are any Records (called atoms in Liquid) that match our Filter. If there are zero Record matching our Raw Transaction Filter, our Action won't fire, preventing an empty report from being sent.
Note: The {% if atoms.size != 0 %} Liquid is essential for this Action to run correctly. If your Action is sending blank notifications double check this configuration.
- The assign statement creates a new variable (named sorted_atoms) to hold all of the Records sorted by the curr_phase_name Field value.
- The for statement loops through each Record in sorted_atoms. Additional Liquid inside of the loop outputs data for each Record.
Note: Ideally this would be a great place to use our Liquid Editor to help us build and test our Liquid/HTML. Unfortunately though, it won’t help us in this case as the Liquid Editor only previews scripts against a single transaction and therefore can’t loop over multiple transactions to provide a list of our Filter's matched transactions. To test this out, you’ll need to actually run your Liquid.
Finally, from the Transaction Filter dropdown, select the Raw Transaction Filter that you created above.
Save your Send Report Action by selecting OK.
Great! Our Action to query for Records matching our Raw Transaction Filter is all set. Now we need to create a Business Rule that sends the Report to the users we specified in Step 2.
4. Configure a Daily Schedule Business Rule
For sending reports, we need to configure a special Business Rule called a Daily Schedule Business Rule. This Business Rule is special because it runs on a nightly basis.
Note: The time zone used by the Daily Schedule depends on which Onit data center your Onit environments lives within. For Onit most clients, this will be 3am CST.
Add a new Daily Schedule Business Rule.
Provide it with a Name.
Daily Schedule Business Rules also accept a Filter. For Daily Schedules used in conjunction with some Action types, we can attach a Raw Transaction Filter. However, when a Daily Schedule Business Rule is used to fire a Send Report Action, it must make use of a Raw User Filter to define which users should receive the reports.
Select the Raw User Filter you created earlier from the Filter dropdown.
Lastly, select your Send Report Action from the Action dropdown.
Tip: Daily Schedule Business Rules in batch processes can be paused or cancelled by the user. Users are also able to resume/retry jobs from the point of cancellation. For more information see this tutorial: Pause / Resume, Retry / Cancel Daily Schedules
Testing Your Report
Excellent! You’ve just created and scheduled an email-based report.
You may not want to wait until 3 A.M. to see if it works the way you expect it to, however. To test out your report, jump back over to your Send Report Action briefly.
For testing purposes, you can turn on the Test Mode property for this Action and provide a Test Email for test reports to be sent to, as shown below:
Select OK to save these updated properties.
Hop back over to your Daily Schedule Business Rule. Select the Execute button to cause your Daily Schedule Business Rule to fire. The email provided in the Action should receive a report if one or more transactions matched your Filter.
Advanced Participant and Pending Endorsement Status Filters
One last thing we'll cover in this tutorial is two special filters that are only used for Send Report Actions.
-
Pending Endorsement Raw Transaction Filter: Let's say you want to find all the transactions that a certain user has pending endorsements on, (that is, their approval or rejection of the transaction is pending). To do so, you can create a Raw Transaction Filter use the following JSON:
[{"type":"user_pending_work","user_id":"{{current_user._id}}"}]
-
Participant Status Raw Transaction Filter: Alternatively, if you want to find all the transactions that a certain user is just a participant of, you can create a Raw Transaction Filter using the following JSON:
[{"type":"user_is_participant","user_id":"{{current_user._id}}"}]
Although these filters are looking for user information in transactions, they are still filtering for transactions. For this reason, make sure you create Raw Transaction Filter with either of these filters and attach them to the Send Report Action. Additionally, you must use these Raw Transaction Filters in conjunction with a Raw User Filter (attached to the Daily Schedule Business Rule) to define which user/s should be used as the current_user variable, (or, in other words, which user/s you want to query transactions for).