Getting Started

Introduction

Forest instantly provides all common admin tasks such as CRUD operations, simple chart rendering, user group management, and WYSIWYG interface editor. That’s what makes Forest a quick and easy solution to get your admin interface started.

This guide assists developers in having the admin completely tailored to cater to their specific needs. We’ve developed Forest so that your admin is 100% customizable. It means that you have full control over your data, your back-end business logic and the UI.

Forest provides a very simple API-based framework to handle all parts of your admin back-end configuration. You should be good to go in no time, with virtually no learning curve.

Live Demo data model

Glossary

Forest allows to handle even the most complex scenarios. The Smart label enables you to implement your own business logic with code, when necessary.

Term	Definition
Admin API	The API generated by the Forest Liana to manage all your application data and business operations.
Collection	A set of records having the same type usually stored in the database.
Data Token	A token used to authenticate your requests on your Admin API.
Field	An attribute of a collection.
Forest Liana	The locally-installed plugin that analyzes your data model and generates the Admin API
Forest UI	The web application of Forest Admin, accessible from any browser at https://app.forestadmin.com
Forest UI Schema	A schema of your data model generated by the Forest Liana in order to initialize your Forest UI
FOREST_AUTH_SECRET	A private token - chosen by yourself - used to sign the data token.
FOREST_ENV_SECRET	A private token - given by Forest Admin - used to identify your project environment in Forest.
Relationship	A connection between two collections.
Segment	A subset of a collection gathering filtered records.
Smart Action	A button that triggers server-side logic.
Smart Collection	A group of records gathered from different sources and implemented following your business logic.
Smart Field	A field that displays a computed value in your collection
Smart Relationship	A relationship that displays a link to another collection.
Smart View	A custom view you can code using HTML/CSS/JSS to display data in any way you want.

How it works

Before you start writing a single line of code, it’s a good idea to get an overview of how Forest with Rails works. The magic of Forest lies in its architecture. Forest is divided into two main components:

• The Forest Liana is an open-source Gem that analyzes all your data model and generate the Admin API.
• The Forest UI (web application), accessible from any browser, that handles communication between the admin user and the database through the Admin API.

When you launch your Rails application, the Forest Liana sends a schema - the Forest UI Schema - to the Forest’s servers to initialize the UI.

Data Privacy

The main advantage of Forest’s architecture is that absolutely no data transits over our servers. The user accesses application data directly from the client and Forest is just deployed as a service to display and interact with the data. Read more about hosting.

With Forest, your data are transferred directly from your application to your browser while remaining invisible to our servers. See how it works.

Security

We use a two-step authentication to connect you to both Forest’s server and your Admin API.

The first step is to retrieve your UI configuration. When logging into your account, your credentials are sent to the Forest’s server which returns the UI token to authenticate your session.

The second step is to authenticate to your Rails app to get access to your data. Your password is sent to your Admin API which returns the data token signed by the FOREST_AUTH_SECRET you chose. Each of your requests to your Admin API are authenticated with the Data Token.

In a nutshell, your admin uses the UI token to make request about the UI configuration. Then the Data Token is used to make queries on your Admin API to manage your data. All our tokens are generated using the JWT standard.

Installation

If you haven’t done it yet, you should have Forest installed on your application. The relevant information is below. You should be set up in no more than a few minutes. If you encounter any issue, feel free to drop us a line at support@forestadmin.com or using the live chat available on our homepage.

Get Started

Get Started

Deploy to production

After installing and customizing (see all the sections below) your admin, it’s time to deploy your Rails application to your production server. Then, you will be ready to onboard all your admin users and start using it in live.

After clicking on the “Deploy to production” link, you must provide your FOREST_ENV_SECRET and the FOREST_AUTH_SECRET in the environment variables of your production server. These variables are used in the config/secrets.yml file.

Then, fill the Application URL field. In our case, the Application URL is https://forest-live-demo.herokuapps.com.

Last but not least, it wouldn’t be convenient to configure your UI from scratch again on your Forest Production environment. Forest gives you the possibility to copy the layout from one environment to another. Here, we will copy the Development environment layout to your Production environment.

You’re now ready to use Forest on production and invite all your teammates!

Admin API

What is the Admin API?

The Admin API is a REST API (encapsulated behind a Rails Engine) generated automatically by the Forest Liana when you launch your Rails application. This API covers all the common requirements of a fully functional Admin Interface (CRUD operations, search & filters, sort, pagination and more). The API is hosted on your side, so you have virtually no limitation to extend it.

However, to ease the customization of your admin, we’ve introduced the concept of Smart features which helps you to fully extend the API.

Before you start to deep dive into this documentation, it’s a good idea to see how the Admin API is designed.

Retrieving the admin user details

Everytime you interact with your application data from the Forest UI, it triggers an API call to your Rails admin backend. This API call is authenticated using the Data Token. This token is a JWT token signed with your FOREST_AUTH_SECRET (see the Security section for more information) and it is passed to the HTTP request through the Authorization header.

The JWT Data Token contains all the details of the admin user. From a route, you can retrieve them with the variable forest_user. On our Live Demo example, we’ve developed a Whoami global Smart Action available that returns the full name of the admin user.

Configuring the CORS headers

You MUST configure the right CORS headers to allow the domain app.forestadmin.com to trigger an API call on your Application URL, which is a different domain name (e.g. localhost:3000 on development).

We use the Rack CORS Gem for this purpose.

Extending the Admin API

Sometimes, you need to extend or completely rewrite the default behavior of an Admin API route. On our Live Demo, we’ve overriden the DELETE /forest/Company/:companyId API call to only allow admin users that are part of the Management team. If you’re in the right team, we call simply default_destroy method to trigger the default destroy implementation.

Actions

What is an action?

An action is a button that triggers server-side logic through an API call. Without a single line of code, Forest supports natively all common actions required on an admin interface such as CRUD (Create, Read, Update, Delete), sort, search, data export.

What is a Smart Action?

Sooner or later, you will need to perform actions on your data that are specific to your business. Moderating comments, logging into a customer’s account (a.k.a impersonate) or banning a user are exactly the kind of important tasks to unlock in order to manage your day-to-day operations.

On our Live Demo example, our Company collection has many examples of Smart Action. The simplest one is Mark as live.

Creating a Smart Action

In the following example, the file lib/forest_liana/collections/company.rb contains the Smart Action declaration. After declaring your Smart Action, your Forest Admin UI will be updated with a new button baring the label of this new action.

If you click on this new button, your browser will make an API call POST /forest/actions/mask-as-live. If you want to customize the call, check the list of available options.

The payload of the HTTP request is based on a JSON API document. The data.attributes.ids key allows you to retrieve easily the selected records from the UI and the data.attributes.values key contains all the values of your input fields (Opening a form to ask input values).

At this time, there’s no Smart Action Implementation because no route in your Admin backend handles the API call yet. In the file config/routes.rb, we’ve declared a new route and we’ve implemented the business logic behind the “Mark as Live” button in a new controller /app/controllers/forest/companies_controller.rb.

Forest takes care of the authentication thanks to the ForestLiana::ApplicationController parent class controller.

The business logic in this Smart Action is extremely simple. We only update here the attribute status of the companies to the value live.

Available Smart Action options

Here are the list of available options to customize your Smart Action:

Name	Type	Description
name	string	Label of the action displayed in Forest.
type	string	(optional) Type of the action. Can be bulk, global or single. Default is bulk. Check the configuring the visibility of a Smart Action section for more details.
fields	array of objects	(optional) Check the Handling input values section.
download	boolean	(optional) If true, the action triggers a file download in the Browser. Default is false
endpoint	string	(optional) Set the API route to call when clicking on the Smart Action. Default is 'forest/actions/name-of-the-action-dasherized'
http_method	string	(optional) Set the HTTP method to use when clicking on the Smart Action. Default is POST.

Opening a form to ask input values

Very often, you will need to ask user inputs before triggering the logic behind a Smart Action.

For example, you might want to specify a reason if you want to block a user account. Or set the amount to charge a user’s credit card. On our Live Demo example, we’ve defined 4 input fields on the Smart Action Upload Legal Docs on the collection Company.

Here are the complete list of available options to customize your input form.

Name	Type	Description
field	string	Label of the input field.
type	string	Type of the input field. Can be Boolean, Date, Number, String, File or Enum.
enums	array of strings	(optional) Required only for the Enum type. This is where you list all the possible values for your input field.
description	array of fields	(optional) Add a description for your admin users to help them fill correctly your form
isRequired	boolean	(optional) If true, your input field will be set as required in the browser. Default is false.

Customizing response

Default success notification

Returning a 204 status code to the HTTP request of the Smart Action shows the default notification message in the browser.

On our Live Demo example, if our Smart Action Mark as Live route is implemented like this:

We will see a success message in the browser”

Custom success notification

If we return a 200 status code with an object { success: '...' } as the payload like this…

… the success notification will look like this:

Custom error notification

Finally, returning a 400 status code allows you to return errors properly.

Custom HTML response

You can also return a HTML page as a response to give more feedback to the admin user who has triggered your Smart Action. To do this, you just need to return a 200 status code with an object { html: '...' }.

On our Live Demo example, we’ve created a Charge credit card Smart Action on the Collection Customer that returns a custom HTML response.

Downloading a file

On our Live Demo, the collection Customer has a Smart Action Generate invoice. In this use case, we want to download the generated PDF invoice after clicking on the action. To indicate a Smart Action returns something to download, you have to enable the option download.

Configuring the accessibility of a Smart Action

3 types of Smart Actions are available in Forest:

• Bulk (default): The Smart Action will be available on one or several records.
• Single: The Smart Action will only be available on a single record.
• Global: The Smart Action will only be available on a Collection and does not target any specific record.

To specify the type of a Smart Action, use the option type.

On our Live Demo example, Mark as Live is a Bulk Smart Action, Upload Legal Dosc is a Single Smart Action and Import data is a Global Smart Action.

Enable/Disable a Smart Action according to the state of a record

Sometimes, your Smart Action only makes sense depending on the state of your records. On our Live Demo, it does not make any sense to enable the Mark as Live Smart Action on the Company collection if the company is already live, right?

In the collection settings, you can configure the UI options of your Smart Actions.

Fields

What is a field?

A field is simply an attribute defined in your database. Examples of fields: first name, gender, status, etc.

Customizing a field

Forest allows you to customize how a field appears in your admin interface. You can rename it, choose the right widget to display (e.g. text area, image viewer, Google map), add a description or even set the read/write access.

To customize a field, go to Collection Settings -> Fields, then select the field to start configuring it.

What is a Smart Field?

A field that displays a computed value in your collection.

A Smart Field is a column that displays processed-on-the-fly data. It can be as simple as concatenating attributes to make them human friendly, or more complex (e.g. total of orders).

Creating a Smart Field

On our Live Demo, the very simple Smart Field fullname is available on the Customer collection.

Very often, the business logic behind the Smart Field is more complex and must interact with the database. Here’s an example with the Smart Field full_address on the Customer collection.

Updating a Smart Field

By default, your Smart Field is considered as read-only. If you want to update a Smart Field, you just need to write the logic to “unzip” the data. Note that the set method should always return the object it’s working on. In the example hereunder, the user_params is returned.

Searching on a Smart Field

To perform a search on a Smart Field, you also need to write the logic to “unzip” the data, then the search query which is specific to your zipping. In the example hereunder, the firstname and lastname are searched separately after having been unzipped.

Available Field Options

Here are the list of available options to customize your Smart Field:

Name	Type	Description
field	string	The name of your Smart Field.
type	string	Type of your field. Can be Boolean, Date, Enum, File, Number or String.
enums	array of strings	(optional) Required only for the Enum type. This is where you list all the possible values for your input field.
reference	string	(optional) Configure the Smart Field as a Smart Relationship.
widget	string	(optional)Configure the widget to display in the browser. Can be color picker, document viewer, file picker, image viewer, JSON editor, link, map, price, rich text editor, text area or text input
isReadOnly	boolean	(optional) If true, the Smart Field won’t be editable in the browser. Default is true if there’s no set option declared.
isRequired	boolean	(optional) If true, your Smart Field will be set as required in the browser. Default is false.

Relationships

What is a relationship?

A relationship is a connection between two collections.

Forest supports natively all the relationships defined in your ActiveRecord models (belongsTo, hasMany, …). Check the Rails documentation to create new ones.

What is a Smart Relationship?

Sometimes, you want to create a virtual relationship between two set of data that does not exist in your database. A concrete example could be creating a relationship between two collections available in two different databases. Creating a Smart Relationship allows you to customize with code how your collections are linked together.

Creating a BelongsTo Smart Relationship

On the Live Demo example, we have an Order belongsTo a Customer belongsTo an Address. We’ve created here a BelongsTo Smart Relationship that acts like a shortcut between the Order and the delivery Address.

A BelongsTo Smart Relationship is created like a Smart Field with the reference option to indicates on which collection the Smart Relationship points to.

Creating a HasMany Smart Relationship

On the Live Demo example, we have a Product hasMany Orders and an Order belongsTo Customer. We’ve created a Smart Relationship that acts like a shortcut with Product hasMany Customer (buyers).

A HasMany Smart Relationship is created like a Smart Field with the reference option to indicates on which collection the Smart Relationship points to.

Upon browsing, an API call is triggered when accessing the data of the HasMany relationships in order to fetch them asynchronously. In the following example, the API call is a GET on /Product/:product_id/relationships/buyers.

We’ve built the right SQL query using Active Record to count and find all customers who bought the current product.

Then, you should handle pagination in order to avoid performance issue. The API call has a querystring available which gives you all the necessary parameters you need to enable pagination.

Finally, you don’t have to serialize the data yourself. The Forest Liana already knows how to serialize your collection (Customer in this example). You can access to the serializer through the serialize_models() function.

Collections

What is a collection?

A collection is a set of data elements physically stored in the database displayed in tabular form (by default), with rows (i.e. records) and columns named (i.e. fields). A collection has a specified number of columns, but can have any number of rows.

Forest automatically analyses your data models and instantly make your collections available in the Forest UI. It covers the majority of use cases. If needed, you can create a Smart Collection to go one step further in the customization of your admin.

What is a Smart Collection?

A Smart Collection is a Forest Collection based on your API implementation. It allows you to reconcile fields of data coming from different or external sources in a single tabular view (by default), without having to physically store them into your database.

Fields of data could be coming from many other sources such as other B2B SaaS (e.g. Zendesk, Salesforce, Stripe), in-memory database, message broker, etc.

Creating a Smart Collection

On our Live Demo, we’ve stored the Legal Documents of a Company on Amazon S3. In the following example, we show you how to create the Smart Collection to see and manipulate them in your Forest admin.

First, we declare the LegalDoc collection in the lib/forest_liana/collections/ directory. In this Smart Collection, all fields are related to S3 attributes except the field is_verified that is stored on our database in the table documents. You can check out the list of available field options here if you need it.

Implementing the GET (all records)

At this time, there’s no Smart Collection Implementation because no route in your Rails app handles the API call yet. In the file /app/controllers/forest/legal_docs_controller.rb, we’ve created a new controller to implement the API behind the Smart Collection.

The logic here is to list all the files uploaded on a specific S3 Bucket. We use a custom service /app/services/forest/s3-helper.rb for this example. The implementation code of this service is available on Github.

Finally, the last step is to serialize the response data in the expected format which is simply a standard JSON API document.

Implementing the GET (specific record)

To access the details view of a Smart Collection record, you have to catch the GET API call on a specific record. One more time, we use a custom service /app/services/forest/s3-helper.rb that encapsulates the S3 business logic for this example.

The implementation of the build_legal_doc() and is_verified?() methods are already described in the Implementing the GET (all records) section.

Implementing the PUT

To handle the update of a record we have to catch the PUT API call. In our example, all S3-related fields are set as read-only and only is_verified can be updated.

The implementation of the build_legal_doc() and is_verified?() methods are already described in the Implementing the GET (all records) section.

Implementing the DELETE

Now we are able to see all the legal documents on Forest Admin, it’s time to implement the DELETE HTTP method in order to remove the documents on S3 when the admin user needs it.

Segments

What is a segment?

A Segment is a subset of a collection gathering filtered records.

Segments are designed for those who want to systematically visualize data according to specific sets of filters. It allows you to save your filters configuration so you don’t have to compute the same actions every day (e.g. signup this week, pending transactions).

Creating a Segment

Forest provides a straightforward UI to configure the segments you want. The only information the UI needs to create a segment within a collection is a name and some filters.

Creating a Smart Segment

Sometimes, segment filters are complicated and closely tied to your business. Forest allows you to code how the segment is computed.

On our Live Demo example, we’ve implemented a Smart Segment on the collection Product to allow admin users to see the bestsellers at a glance.

You’re free to implement the business logic you need. The only requirement is to return a valid Active Record condition. Most of the time, your Smart Segment should return something like { id: [ 1,2,3,4,5 ] }.

On our implementation, we use a raw SQL query to filter and sort the product that was sold the most.

Analytics

As an admin user, KPIs are one of the most important things to follow day by day. Your customers’ growth, Monthly Recurring Revenue (MRR), Paid VS Free accounts are some common examples.

Forest can render three types of charts:

• Single value (Number of users, MRR, …)
• Repartition (Number of users by countries, Paid VS Free, …)
• Time-based (Number of signups per month, …)

Ensure you’ve enabled the Layout Editor mode to add, edit or delete a chart.

Creating a Chart

Forest provides a straightforward UI to configure the charts you want.

Simple mode

The only information the UI needs to handle such charts is:

• 1 collection
• 1 aggregate function (count, sum, …)
• 1 group by field
• 1 time frame (day, week, month, year) option.
• 1 or multiple filters.

Creating a Chart on a specific record

Premium feature

Forest’s dashboard is handy when it comes to monitoring the overall KPIs. But you may find the analytics module useful for a more in-depth examination of a specific company, user or any other items.

“Analytics per record” only supports the Smart and Query mode.

• For Query charts, use the character ? to inject the current record the user is currently seeing to your query. More details here.
• For Smart charts, the parameter record_id is automatically passed in the HTTP body to access the record the user is currently seeing.

Creating a Chart with SQL

Premium feature

The Query mode has been designed to provide you with a flexible, easy to use and accessible interface when hard questions need to be answered. Simply type SQL queries using the online editor and visualize your data graphically.

Single value

The returned column must be name value. In the following example, we simply count the number of customers.

Single value (with growth percentage)

The returned columns must be name value and previous. In the following example, we simply count the number of Appointments booked in January 2018 and compare this value to the number of Appointments booked in the previous month.

Repartition

The returned columns must be name key and value. In the following example, we simply count the number of transactions distributed by status.

Time-based

The returned columns must be name key and value. In the following example, we simply count the number of appointments per month.

Analytics per account

If you put the character ? in your SQL query, it will automatically be replaced by the current record opened in your Admin. Most of the time, it’s required if you have charts declared in the Analytics per Account section.

Don’t forget this special character with quotes if the type requires it.

In the following example, we compute the number of transactions per month for the company “Deliveroo”. The companies.id is an integer here, so there’s no need to quote it.

Creating a Smart Chart

Sometimes, charts data are complicated and closely tied to your business. Forest allows you to code how the chart is computed. Choose “Smart” as the data source when configuring your chart. Forest will make the HTTP call to Smart Chart URL when retrieving the chart values for the rendering.

Value Smart Chart

On our Live Demo, we have a MRR value chart which computes our Monthly Recurring Revenue. This chart queries the Stripe API to get all charges made in the current month (in March for this example).

When serializing the data, we use the serialize_model() method. Check the value syntax below.

Repartition Smart Chart

On our Live Demo, we have a Charges repartition chart which shows a repartition chart distributed by credit card country. This chart queries the Stripe API to get all charges made in the current month (in March for this example) and check the credit card country.

When serializing the data, we use the serialize_model() method. Check the value syntax below.

Time-based Smart Chart

On our Live Demo, we have a Charges time-based chart which shows the number of charges per day. This chart queries the Stripe API to get all charges made in the current month (in March for this example) and group data by day.

When serializing the data, we use the serialize_model() method. Check the value syntax below.

Views

What is a view?

A view is simply the way to visualize your data in the Forest UI. By default, Forest renders your data using a table view when you access multiple records and a form view to access, edit and create a specific record.

What is a Smart View?

Premium feature

Smart Views lets you code your view using JS, HTML, and CSS. They are taking data visualization to the next level. Ditch the table view and display your orders on a Map, your events in a Calendar, your movies, pictures and profiles in a Gallery. All of that with the easiness of Forest.

Creating a Smart View

Forest provides an online editor to inject your Smart View code. The editor is available on the collection’s settings, then in the “Smart views” tab.

The code of a Smart View is an Ember Component and simply consists of a Template and Javascript code.

Getting your records

The records of your collection is accessible from the records property. Here’s how to iterate over them in the template section:

Accessing a specific record

For each record, you will access its attributes through the forest-attribute property. The forest- preceding the field name is required.

Accessing belongsTo relationships

Accessing a belongsTo relationship works exactly the same way than accessing a simple field. Forest triggers automatically an API call to retrieve the data from your Admin API only if it’s necessary.

On the Shipping Smart View (in the collection named Order) defined on our Live Demo example, we’ve displayed the full name of the customer related to an order.

Accessing hasMany relationships

Accessing a hasMany relationship works exactly the same way than accessing a simple field. Forest triggers automatically an API call to retrieve the data from your Admin API only if it’s necessary.

Refreshing data

Trigger the fetchRecords action in order to refresh the records on the page.

Fetching data

Trigger an API call to your Admin API in order to fetch records from any collection and with any filters you want.

We will use the store service for that purpose. Check out the list of all [available services] from your Smart View.

On our Live Demo example, the collection appointments has a Calendar Smart View. When you click on the previous or next month, the Smart View fetches the new events in the selected month. The result here is set to the property appointments. You can access it directly from your template.

Available parameters

Parameter	Type	Description
filter	Object	A list of filters you want to apply. Example filter: { date: '>2018-01-28,<2018-03-11', name: 'Manuela Nolan' }.
filterType	String	and or or.
timezone	String	The timezone string. Example: America/Los_Angeles.
page[number]	Number	The page number you want to fetch.
page[size]	Number	The number of records per page you want to fetch.

Deleting records

The deleteRecords action lets you delete one or multiple records. A pop-up will automatically ask for a confirmation when a user triggers the delete action.

Triggering a Smart Action

Here’s how to trigger your Smart Actions directly from your Smart Views. You can pass an array or a single record. The first argument is the collection that has the Smart Action. The second argument is the Smart Action name, here Reschedule, and the third argument is an array of records or a single one.

Available properties

Forest automatically injects into your Smart View some properties to help you display your data like you want.

Property	Type	Description
collection	Model	The current collection.
currentPage	Number	The current page.
isLoading	Boolean	Indicates if the UI is currently loading your records.
numberOfPages	Boolean	The total number of available pages
records	array	Your data entries.
searchValue	String	The current search.

Available actions

Forest automatically injects into your Smart View some actions to trigger the logic you want.

Action	Description
deleteRecords(records)	Delete one or multiple records.
triggerSmartAction(collection, actionName, record)	Trigger a Smart Action defined on the specified collection on a record.

Examples

On our Live Demo, we have 4 Smart Views defined:

• a Map view defined in the deliveries collection.
• a Calendar view in the appointments collection.
• a Shipping view in the orders collection.
• a Gallery view in the products collection.

Example: Map view

Example: Calendar view

Example: Shipping view

Example: Gallery view

Integrations

Forest is able to leverage data from third party services by reconciliating it with your application’s data, providing it directly to your admin. All your admin actions can be performed at the same place, bringing additional intelligence to your admin and ensuring consistency.

Stripe

Premium feature

Configuring the Stripe integration for Forest allows you to have your customer’s payments, invoices and cards alongside the corresponding customer from your application. A Refund Smart Action is also implemented out-of-the-box.

On our Live Demo, we’ve configured the Stripe integration on the Customer collection. The Stripe Customer ID is already stored on the database under the field stripe_id.

Available options

Here are the complete list of available options to customize your Stripe integration.

Name	Type	Description
api_key	string	The API Secret key of your Stripe account. Should normally starts with sk_.
mapping	string	Indicates how to reconcile your Customer data from your Stripe account and your collection/field from your database. Format must be model_name.stripe_customer_id_field