Introduction to App Builder - Lesson 3: Create rules

This is the third lesson of the Introduction to App Builder tutorial series.

Business layer

In the previous lesson, we created and configured a table to hold our application's data. We did that in the first of App Builder's layers: the data layer. However, storing data is all that the tables do. To allow your end users to see or interact with this stored data in any way, we need business objects, also called rules. These can be created in the business layer, which is where we'll work now.

Create a source object

We'll start by creating a specific type of rule called a source object. The purpose of this rule is to expose the contents of a given table in the data layer of your application. To create one, follow these steps:

Access your application's App Workbench.
Go to the Rules tab and click the + Rule button. The Rule Builder page opens:
In the Name field, enter the name Region (Source).

Note

According to App Builder's naming conventions, rule names should be the same as the table they modify, with its purpose in parentheses.
In the Purpose field, select Business Object.
In the Target field, select Region, the table we've previously created.
(Optional) In the Technical Help field, enter a description of the purpose of this rule. This information will not be visible to final users; it is meant to assist other developers.
Click Create.

App Builder will create the rule. After that, the screen will automatically enter edit mode for the new rule, allowing you to continue configuring it.

Set up functionality for a source object

When you create a new rule, App Builder automatically enters edit mode for it, and you can start adding functionality. If you've exited edit mode for the Region (Source) rule you've just created, find it in the App Workbench > Rules tab, and either double-click its row in the list or click the pen icon at the end of the row to enter edit mode again.

The Tables tab shows where the rule obtains its data. Although rules can only modify the data in one table (the one you select during rule creation), they can get data from multiple tables. The rule we're creating now, however, has the purpose of simply showing what's in the Region table, so that's the only one we need. Because we've selected the Region table as our rule's target, App Builder already shows it in the Tables tab, so we don't need to add it.

The next step is to select which columns we want to work with. App Builder doesn't automatically select all columns from the tables because there may be a very large number of them; therefore, you must select the columns you need manually:

In the Tables tab, where the Region table is being displayed, select the checkboxes for both the RegionID and the Region columns. Don't select the columns that were created by the audit lite function.

Once you've selected both columns, click the Columns panel, which should now have a (2) at the end, indicating how many columns you've picked. It should look like this:
Click the Results button in the Rule panel to make sure that the results are being shown correctly.

Note

It is good practice to periodically click the Results button while you're setting up a rule.

Practice time: Create source objects

It's time to practice what you've learned. The application we're creating will need data from several tables present in the Northwinds database. Go over the tables listed below and create source objects for each one following the steps described above. You can find + Rule buttons in the App Workbench home page, or in its Rules tab.

Category
Customer
Employee
OrderDetail
Order
Parameter
Product

Create a list object

Now, we'll create another type of rule called a list object. List objects are what we use to create dropdown menus in our App Builder applications. List objects are quite simple to create because they only require two columns: a primary key (PK), and a title. Let's create a list object based on Category, one of the tables present in the Northwinds database. Follow these steps:

From the App Workbench > Rules tab, click + Rule like we did before for the source object.
In the Name field, enter the name Category (List).

Note

According to App Builder's naming conventions, list object names should be the same as the table they pull data from, with the word "List" in parentheses.
In the Purpose field, select List.
In the Target field, select Category.
Click Create.
Once App Builder creates the rule, you will see the columns of the Category table listed in the Table tab, where you can choose which columns to use. App Builder automatically selects the primary key of the table because that's what it uses to identify the records, but you should pick a column (just one) with human-legible data to be displayed in the dropdown menu that this object will build. For this exercise, select the Category column.
In the Columns tab, use the Usage Type column to indicate to App Builder what each column will be used for. This will help accelerate our development process later on as it will allow for some fields to be automatically populated. Select Key for the CategoryID column and Title for the Category column.
Click Results in the Rule panel.

That's it, we've created a list object. If you've followed the steps above, your Columns panel should look like this:

Columns panel 2 - Rule builder

Practice time: Create list objects

Our application is also going to need list objects based on several of the tables in the Northwinds database. To practice what you've learned and create the required objects needed for the application, create list objects for the following tables:

Category (done above)
Customer
Order
Product

The Concat function

When you're creating list objects, there isn't always a column in the table that is an ideal option for a title, that is, the human-legible information that will ultimately be shown in the application UI. For example, in the App Workbench > Tables tab, select the Employee table and take a look at its Results. Which column would you choose if you wanted to create a list object based on this table? There isn't an obvious pick.

However, there is a FirstName and a LastName column, and combining data from them might be the best option. For this, we'll use an App Builder function: Concat().

Let's create a list object based on the Employee table. Follow these steps:

From the App Workbench > Rules tab, click + Rule.
In the Name field, enter Employee (List).
In the Purpose field, select List.
In the Target field, select Employee.
Click Create.
Once App Builder creates the rule, it will automatically select the primary key. Now, to use the Concat function to combine the FirstName and LastName columns into one, go to the Columns tab and click + Column there. The Column - Add column dialog opens:

Note

There is also a + Column button in the Table tab. It works the same way.
In the Column or Expression textbox, enter the columns that you want to combine. When you start typing the name of a column, a list of options will appear where you can click the one you're looking for. Double pipes (||) represent the Concat() function. Remember to add an empty space between the FirstName and LastName columns, so the final result will be legible. So, to combine these two columns into one, enter:
```
E.FirstName||' '||E.LastName
```
Further reading

Concat() mvSQL database function in Jitterbit App Builder
In the Alias and Target section, enter Full Name in the Alias field. This field identifies the new column you're creating.
Click Save. The Columns panel should look like this:
Click Results to make sure the new Full Name column is showing correctly.

Rule creation accelerator

You've created quite a few source and list objects manually, but App Builder offers a faster way to do this process. Using the accelerator, you can create rules directly from the data layer, allowing App Builder to use the configuration of a table as a guide to set up rules derived from it:

Navigate to App Workbench > Tables and open the Region table.
In the Table panel, there is a section titled Accelerators. Click the Publish to Business Layer button. App Builder will ask for confirmation that you are trying to create business object and list rules. Click Proceed.

App Builder will take a few moments to create the two rules, then it will show you a confirmation message. If you visit App Workbench > Rules now, you'll see that the Region table now has two rules based on it. They are identical to the ones you've created manually for the other tables.

Note

The accelerator uses the more generic descriptor "Business Object" instead of "Source" in the parentheses of the source object. This does not affect how it works.

Now, to practice using the accelerator as well, use it to create rules based on the two remaining tables: Shipper and Supplier.

Review and wrap-up

Let's review what we've done in this lesson. We started with the tables we learned about in the previous lesson and used them to create business objects, or rules, which can show the data from the tables in our application's UI. We learned about and created two types of rules: source objects and list objects.

Now we are ready to move on to the third layer of development in App Builder, the UI layer. Go to Lesson 4: The UI layer.