Using Badges to Enhance App Orchestration Visibility and Workflow

by Christina Moore Updated Aug 16, 2018

Your business case may require an App whose primary responsibility is to orchestrate the firing of Actions on a large number of Records. The Earn Badge Action can be used to support workflows that require orchestrator Apps by providing visibility into the progress of work across these Records and information on the success or failure of that work. Workflow following the conditional success or failure of a batch of work is also supported by this Action.

A good use case for the Earn Badge Action is a budgeting process, where forecast values must be recalculated on a monthly basis. With an Earn Badge Action, an App Creator can configure a Portal Widget to display on the orchestrator Record which shows how many forecast Records are pending an update, how many were successfully updated and how many failed an update. When all forecast records have been recalculated, a Conditional Action can send a success or failure email to the user that is responsible for managing this monthly process.

The Earn Badge Action is a very versatile Action. Advanced workflows can be supported with this type of Action where multiple Earn Badge Actions are configured to take Records through multiple sets of Actions on reoccurring and conditional bases.

Note: The Earn Badge Action is still in beta testing. For the time being, it continues to undergo changes that may break the configuration and require you to manually adjust your Action's setup.

How the Earn Badge Action Works

Where is the Earn Badge Action configured?
The Earn Badge Action is configured on an App to track progress of one or more Actions on a set of target Records. We will refer to the App where the Action is configured as the Orchestrator App, and the App containing Records with Actions to be fired on them as the Target App.

Often the Orchestrator App and the Target App have a parent-child relationship, where the parent has a long list of children that it is responsible for orchestrating the triggering of Actions on. However, your use case may require that the Orchestrator App and the Target App are not related, or alternatively, that they are the same App; that is, the App the Earn Badge Action is configured on triggers Actions on itself.

What is a Badge?
When the Earn Badge Action first fires, it issues a "badge" for each of the target Records. Badges are never seen by either the end user or App Creators; rather, they are maintained in a background database and are responsible for tracking the status of the Actions the orchestrator App must trigger for each target Record. A badge can either be in the state of Pending, Working, Success, or Failure. App Creators can use special Liquid Filters to access information about the status of badges. (More on these Filters later).

What happens when an Earn Badge Action is being processed?
After an Earn Badge Action is fired, it takes a moment to create badges for each of the target Records. Once each target Record has a corresponding badge in the background database, the Earn Badge Action begins running each target Record through the Actions provided in the Earn Badge Action.

For instance, your Earn Badge Action may be configured to fire an Update Transaction Action and an Add Comment Action on each target Record. The target Record's badge will be in a state of Pending when it first receives the badge, a state of Working while the Update Transaction Action and the Add Comment Action are being triggered on the Record, and either a state of Success if both Actions were completed successfully on the Record, or a state of Failure if one or more of those Actions resulted in an error and failed to complete.

After every target Record has gone through the process of having the set Actions triggered on them, resulting in all badges being is either in a state of Success or Failure, the orchestrating Record then receives its own badge. This orchestrator badge is distinct from the badges received by the target Records since it signals all target Records have completed earning their badges.  Earn Badge Action can now begin any Actions configured to be triggered when all the target Records have completed their badges.

Once the orchestrating Record has this badge, it can optionally trigger one or more Actions on itself. A customizable Condition can also provide criteria that will conditionally fire Actions based on whether the Earn Badge Action was successful or not successful as a whole.  

For example, after all target Records have received their badges, the Earn Badge Action could change the Phase of the orchestrating Action. Additionally, if all target Records' badges completed in a state of Success, a Send Notification Action could send an email to a participant stating the Earn Badge Action was successful. Likewise, if one or more of the Records' badges completed in a state of Failure, a Send Notification Action could send an email providing information about the failure of the Earn Badge Action.

Before We Start ...

Let's Get Started!

1. Turn on the Badges Beta Features

The Earn Badge Action is still undergoing beta testing. Before configuring this Action, you should be aware that breaking changes may be made to this feature's code and may require you to manually change this Action's configuration.

To turn on the Badges Beta Feature, navigate to your corporation's Administration page and select Edit Corporation from the left-hand menu.

Select the Beta Features tab.

Select the Badges (Experimental, breaking changes likely) checkbox.

Select Update to save.

2. Configure the Earn Badge Action

Navigate to the Actions node of your Orchestrating App.  

Add a new Earn Badge Action.

The configuration of this Action is highly customizable. We'll run through some tips for configuring the available properties and then show a quick example of a possible configuration:

  • Badge Name: This is the name of the badge that will be earned by the Orchestrating App after all target Records have completed earning their badges. App Creators often include this name in the Portal Widget we'll configure in Step 3.
  • Badge Work Type: This property determines what type of relationship the App and the Action are supposed to track progress on:
    • Direct Action: If your Orchestrating App and your Target App are the same, you'll want to choose this option. You will need to define the Orchestrating App under App if you select this option.  You do not need to define the Relationship, or App Filter property .
    • Loop on Related Transactions: If badges should be earned on a related App's Records, you'll want this option. If you select this option, you'll also need to select the related Field name for the Relationship property below.  You also need to define the App, which is related by the Relationship Field. 
    • Loop on Filtered App: If badges should be earned on an unrelated App's Records, use this option. You can then select the Orchestrating App for the App property and select a Filter for the App Filter property.
  • Actions: Select the Actions the target Records will need to process in order to earn their badge in the order that they should be triggered. The Actions selected here should belong to the related, filtered App.  Only in the case of Direct Action being selected as Badge Work Type do the actions belong to the current App.
  • Actions to run when complete: You can optionally provide one or more Actions that should be triggered after all the target Records have earned their badges.  Actions ALWAYS belong to the Current App.
  • Success Condition: You can optionally trigger Actions if Records meet or fail to meet some criteria. This property comes populated with a condition that will check to ensure the number of target Records with badges equals the number of successful badges received.
  • Actions to run when successful: You can optionally use this property to trigger any Actions when your Success Condition is met, (i.e., returns a value of `true`).  Actions ALWAYS belong to the Current App.
  • Actions to run when not successful: Similarly, you can optionally use this property to trigger any Actions when your Success Condition is not met, (i.e., returns a value of False).  Actions ALWAYS belong to the current App.

Let's look at an example configuration quickly. In the screenshot below, we're configuring an Earn Badge Action on an Orchestrating App that is responsible for executing some Actions on a Target App:

  1. The Actions, which were previously configured on the child App, update each Target App's child Record and add a comment to it.
  2. Once all children Records have received their badges, the Orchestrating App fires an Add Comment Action to add a comment to the orchestrating Record.
  3. A success condition checks to see that all the child Records have successfully earned their badges.
  4. If successful, they fire a Send Success Notification Action.
  5. If unsuccessful, they fire a Send Failure Notification Action.

3. Configure a Portal Widget to Visualize the Action's Results

The last thing you'll need to do is configure a Portal Widget that will provide your end users insight into the progress, success, and failure of the Earn Badge Action.

You'll want to use the following Liquid filters to retrieve this information:

{{atom.badges.last.name}}
{{atom.badges.last.total_time}}
{{atom.badges.last.child_badges.size}}
{{atom.badges.last.failed_badges.size}}
{{atom.badges.last.successful_badges.size}}

Below is some HTML that will build out a very simple Widget to get you started. However, in more advanced configurations you may use Liquid and Javascript to create a more dynamic presentation for this information:

<table align="center" width="100%">
<tbody>
<tr>
  <td>
  <div class="counterwidget panel" style="margin: 0; box-shadow: 0 2px 2px 0 rgba(0,0,0,.14),0 3px 1px -2px rgba(0,0,0,.2),0 1px 5px 0 rgba(0,0,0,.12) !important;">
    <table align="left" width="90%" style="margin:10px; font-size: 13px; color: #000; background-color: #fff; border-top: 0px; padding-top: 0px; padding-bottom: 0px;">
      <tbody>
      <tr>
        <td><b>Badge earned:</b></td>
        <td>{{atom.badges.last.name}}</td>
      <td><b>Total:</b></td>
      <td>{{atom.badges.last.child_badges.size}}</td>
      </tr>
      <tr>  
        <td><b>Status:</b></td>
        <td>{{atom.badges.last.status}}</td>       
      <td><b>Succeeded:</b></td>
      <td>{{atom.badges.last.successful_badges.size}}</td>
      </tr> 
      <tr>
        <td><b>Total Time:</b></td>
        <td>{{atom.badges.last.total_time}}</td>
      <td><b>Failed:</b></td>
      <td>{{atom.badges.last.failed_badges.size}}</td>
      </tr>
      </tbody>
    </table>
  <div class="clearfix"></div>
  </div>
  </td>
</tr>
</tbody>
</table>

Below is a screenshot of that Portal Widget rendered on the View Page:

For help configuring a Portal Widget, you can check out our Customizing View Pages with Portal Widgets tutorial.

4. Add an Action Button to Fire the Action

Your Earn Badge Action can be triggered as part of your Orchestrating App's workflow but it is most common to configure an Action Button to fire it.

For purposes of this tutorial, we have created an Action Button named Earn Updated Badge.

For help configuring an Action Button, check out our Creating a Button to Execute an Action tutorial.

Test It Out!

That's all there is to setting up a basic Earn Badge Action.

You can test out your configuration by hopping over to one of your Orchestrating App's Records and using the Action Button. Notice that your Portal Widget's data will update at minimum every five seconds, displaying how many badges are still pending, are successful or have failed.

Previous Article Configuring a NetDocuments Integration
Next Article Liquid Reference

© 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.