Onit Documentation

Building Your First App

by Christina Moore Updated on

No matter what type of business problems you are ultimately aiming to solve with Onit, you’ll always start by creating a basic App.

To do so, you’ll run through a simple Wizard, which will prompt you to create your App’s most fundamental components: its name, Fields, Roles, and Phases (among other things). Once you complete the Wizard, your new App will be created.

In this tutorial, we’ll walk through the process of creating a brand new App from scratch using the Wizard. We’ll take you step-by-step through the process of launching the Wizard and moving through its screens. Along the way, we’ll highlight the Wizard’s most important settings and configuration options.

Basic vs. Advanced Configuration

Before we get started, it’s important to understand what overall role the Wizard is designed to play.

The Wizard is only intended to initially create an App with very basic functionality. In other words, once you complete the Wizard, your new App won’t be able to do very much - the Wizard just gets you off the ground.

To expand an App’s functionality past this point, you’ll mostly do so outside of the Wizard on your App’s Advanced Designer page. From this page, you can do things like set up routing rules, build email notifications, create buttons and user interface actions, and much more.

It may be helpful to think about the overall App creation process from this macro vantage point:

  • Step 1: Use the Wizard to create a new App with very basic functionality.
  • Step 2: Now that your App exists, use its Advanced Designer page to significantly expand its functionality. The sky is the limit here!

The steps above are cheating a little bit. There is some advanced configuration that can be done within the Wizard, but for now, let’s run with the understanding laid out above.

In this tutorial, we’ll focus exclusively on Step 1.

To tackle Step 2, check out the many other tutorials that we have available, and focus on the topics that align with the business problems you’re aiming to solve.

Let's Get Started!

Our goal in this tutorial will be to create a basic App that handles contract approvals.

When we’re done, our new App will allow users to fill out a simple form to request that an uploaded contract document be routed to a specific person for approval. The form that we will create will prompt the user to enter data, like the name of the customer that the contract is associated with, the contract amount, etc. During the tutorial, we’ll create Fields to identify exactly what data a user should enter.

Here’s a word that you’ll see a lot of when reading Onit tutorials: Record. In the basic app that we’ll be creating, each individual contract that needs to be approved is a Record. Apps are made up of individual Records that all look and behave according to the same predefined rules. In our example, if 50 users submitted contracts for approval, our App would be responsible for managing 50 individual Records, each of which could be in various stages of its overall lifecycle (e.g., pending approval, approved, etc.).

Step 1: Launch the Wizard

To create a brand new App, start by browsing to your Onit homepage, clicking the + button in the top-right corner of the screen, and then clicking Create App.

When prompted to name your App, enter a name that will be meaningful and friendly to your end-users. When you’re done, click Create to launch the Wizard.

Step 2: "General"

The Wizard is broken up into a series of different screens, the first of which is named General.

The General screen enables you to configure a variety of basic options. Most of the settings are obvious from their name, and for many Apps you can stick with the default settings.

That said, let’s focus on one setting in particular: the Phases checkbox.

We haven’t covered what Phases are just yet, but note that if you unselect this checkbox then one of the tabs at the top of the wizard (the tab named Phases) will disappear.

We’ll cover Phases in more detail later, but for now, note that you can create an App with or without Phases enabled. For our App, we do want Phases enabled, so leave this checkbox selected.

Let’s breeze past the General screen with all the default settings selected. Click the Wizard’s Next button to move to the second screen.

Step 3: "Roles"

Everyone that interfaces with your App will play a specific Role. Using the Roles screen, you can define exactly what those roles will be.

For a brand new App, two Roles will always be created for you:

  • Requester: The person that initially creates a Record. In our case, that’s the person who is requesting a new contract be approved.
  • Approver: The person who is responsible for reviewing a Record and approving or rejecting it.

To keep things simple for this tutorial, we’ll stick with the default Approver Role as our only approver and just go through the steps of assigning this Role to a specific person: a user named Mike.

That being said, in many cases, you’ll want to add in more approval complexity to your App. For instance, Onit allows you to create multiple “approval” Roles, where each one approves different aspects of the Record (e.g., Legal Approver, Financial Approver, Compliance Approver). In addition, as opposed to hardcoding a role to the same person for each and every Record (Mike in our case), Onit allows you to assign Roles conditionally, based on predefined rules (e.g., assign Mary as the Legal Approver if the transaction is worth over $1,000; otherwise assign Jim). The App that we will build in this transaction won’t include these levels of complexity, but look for other Onit tutorials that cover these topics.

Let’s assign Mike to be our Approver. To do so, we just need to hardcode Mike’s email address into this Role’s Email property. Select the Approver Role on the left and then type in Mike’s email address on the right.

Before we move on to the next screen, let’s do one last thing: create a brand new Role.

Currently, our App will facilitate communication and approval between the Requester and the Approver. This will work fine for us, but let’s say that there is also a third type of user that would like the ability to simply view transactions. This user doesn’t want to necessarily create new Records, or approve Records -- they simply want to log into Onit from time-to-time and look through all Records.

We’ll call this Role FYI, and we’ll assign it to a user named Sarah.

To create a new Role, click Add at the bottom of the Wizard’s Roles screen. Select the new role on the left and make the following changes to it:

  • Name the Role FYI.
  • Assign the Role to Sarah by entering Sarah’s email address.
  • For Role Type, select Read Only Reviewer.

It’s not necessary to also select the Read Only checkbox. Selecting Read Only Reviewer will ensure that this Role has only read-only access to all transactions.

We’re done with Roles screen. Click Next to move on to Wizard’s next screen.

Step 4: "Tabs"

When users interact with your app, they will do so in two primary contexts:

  • By creating a brand new Record from your App’s Launch page.
  • By viewing and/or editing an existing Record from your App’s View page.

When you create a new App (like we’re doing), Onit will automatically assign a default visual layout to your App’s pages. If necessary though, you can customize this layout by editing options on the Wizard’s Tab screen. This gives you control over exactly what end users will see when they work with your App.

For instance, you can organize where Fields and other data is presented to users. Maybe you want to organize the presentation of Fields into visually separated sections on the Launch page. Or, maybe you want to only display a certain Tab on the App’s View page if a specific condition is met (like a Field’s input equaling a predefined value). These are the types of customizations that you can make from the Wizard’s Tab screen.

The Wizard is not the only place where you can customize an App's View page. For more options, check out the Widget and App Panels pages, which can be accessed from an App's Advanced Designer page.

For our basic App, we’re going to mostly stick with the default settings, as those will suffice. That being said, there is one quick change that we need to make.

Remember the FYI role that we created on the Wizard’s previous screen? We need to assign that role to at least one tab. This is a requirement for each and every role in your App: they all must be assigned to at least one Tab. If this was not a requirement, then users assigned to these roles would not be able to see any of the App’s Records.

At the minimum, whenever you create a new role you’ll usually want to assign it to the second Tab listed on the left (outlined in the screenshot below). That’s because this Tab displays all of an App’s Fields by default.

Let’s assign FYI to this Tab. Select the second Tab, and then add FYI to the Visible for Roles property on the right.

We’re done with Tabs. Click Next to move on to Wizard’s next screen.

Step 5: "Fields"

On the Fields screen, we’ll create the Fields that will prompt our App’s requesters to provide specific information about the Record they are submitting. After a requester populates these Fields on the App's Launch page, the data will be available for viewing and editing on the Record’s View page.

By editing a Field's properties (on the Wizard's Fields screen), it's possible to control whether a Field displays on either the Launch or View page, or both. It's also possible to specify which Tab the Field appears in, and to set conditions around when it should be visible. For now, we’ll stick to the App’s defaults and allow the Fields that we create to display on both Launch and View pages.

You’ll notice that your new App comes with a few Fields: requester_name, requester_email, and name. These Fields cannot be deleted and will be required for every transaction a user creates. Leave the settings for these Fields as they are and let’s create some brand new Fields.

For this tutorial, we’ll create three new Fields to gather the following information:

  • Contract document
  • Amount of the contract
  • Department associated with the contract

To add a new Field, select the Add button in the lower left-hand corner of the Wizard. Notice that a new Field is added to the list of Fields in the left pane.

Provide this Field with a Name under its Properties section. Notice that once you remove your cursor from the Name property, the Field’s Label property will update to match the input of the Name Field.

The Name property doesn’t allow you to type capital letters or spaces, although the Label property does. You can separate words in your Name property with an underscore and watch as the Label updates to include spaces and capitalization. The Label can also be changed to something different than the Name’s value.

You’ll also need to set a Type for each Field. There are many different types of Fields, which can be leveraged to facilitate the information-gathering process for a transaction. In this tutorial, we’ll use the following Field types:

  • Attachment Field, which will allow requesters to upload the contract document.
  • Currency Field, which a requester will use to provide the contract’s amount.
  • Combo Field, which will allow an App's creator to list different departments for a requester to choose from.

Create these three new Fields by selecting the Add button, providing each with an appropriate Name, and selecting the appropriate Field type from the Type dropdown.

Additionally, for the Combo Field, we’ll need to provide some options for a user to select. This can be done by entering our company’s department names (separated by commas) in the combo Field’s Values property.

That’s all for the Fields screen. Select Next to move on to the Phases screen.

Step 6: "Phases"

Finally, in the Phases screen, we’ll configure the different Phases that we want each of our App’s transactions to travel through. For this tutorial, we’ll keep the configuration simple: we’ll create a Phase to show a transaction is "pending approval" and a Phase to show it has been "approved."

Keep in mind that Phases can be a powerful tool for enhancing the workflow of your Apps. Although this App will require a participant to manually advance through our Phases, Phases can also be set up so transactions automatically advance transactions through them depending on the approval of some or all participants within each Phase. Business logic can also be built around Phases so that transactions will only go through specific Phases when certain conditions are satisfied.

Under the Phases screen, you’ll notice that there is a Phase already created. Select it so that we can customize it by:

  • Renaming it to Pending Approval.
  • Unselecting the Auto Advance on Approval Completion checkbox in the Rules section. This property is used to automatically advance a Record to the subsequent Phase after it has received approval. For this basic app we’ll unselect it and require that our Records be manually advanced.

You’ll notice that our Roles have automatically been added to the Roles section of this first phase. Note that every Role must be associated with a single phase as this will determine when in a Record’s workflow participants with that role become active.

Next, create a new Phase by selecting the Add button to the bottom center of the Wizard. Similarly change its Name, this time to Approved, and unselect the Auto Advance on Approval Completion checkbox. We don’t need to assign any Roles to this Phase since a Role may only be associated with a single Phase and we want all our participants for this App to become active in the first Phase.

We’re all done with the Phases for our App. It’s time to wrap this tutorial up by saving our work.

Step 6: Save Your New App

Select the Next button to proceed to the Wizard's Summary screen. Under this screen you can view a brief overview of what changes you made and optionally provide any comments about these changes.

Most importantly, you’ll need to select the Update button at the bottom right of the Wizard to save all your hard work.

Congratulations! You’ve created your very first App!

Take a moment to play around with it. Launch a new Record and visit it from the App’s dashboard. You can make a comment, add a new participant, edit its details, and change its Phase.

Your new App doesn’t do a whole lot yet, but don’t be discouraged. There’s a lot more you can do to build out the powerful, dynamic solutions your business problems have been waiting for.

And remember: after creating an App using the Wizard, most of its configuration takes place within the App’s Advanced Designer. Take a dive into our other tutorials to get a feel for the different ways you can enhance your App.

Next Article Crash Course on Liquid

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