Handbook For Open Foris Arena

Open Foris Arena
ver. 1.0
Handbook
11 August 2021
Open Foris Team
Forestry Division, FAO

Open Foris Arena - Handbook
Content
1. Introduction 4
2. Typical working process 5
3. Access to Open Foris Arena 5
4. Main user interface 7
5. Selecting and creating a survey 8
6. Arena Home 10
6.1. Edit survey info (metadata) 11
6.2. Publish a survey 12
6.3. Delete a survey 13
6.4. Collect Import Report 14
7. Survey 16
7.1. Form Designer 17
7.1.1. About the Form Designer user-interface 17
7.1.2. Data types 19
7.1.3. Description of properties 20
7.1.4. Units of measurements 21
7.1.5. Summary on survey schema 21
7.2. Expressions and expression editor 23
7.3. Hierarchy 26
7.4. Categories 28
7.5. Taxonomies 34
8. Templates 36
8.1. Using a template file 36
8.2. Getting a new template into Arena 37
9. Data 38
9.1. What are the data entry stages? 38
9.2. Adding and editing records 39
9.3. Deleting a record 42
2
9.4. Data Explorer and aggregating data 43
9.5. Export all data into CSV 47
9.5. Import data from Collect/Collect Mobile file 48
9.6. Validation report 49
10. Analysis 50
10.1. Creating a processing chain 50
10.2. RStudio in programming and data processing 54
11. Users and access to Arena 58
12. Examples of expressions 62
12.1. “Relevant if” and “Apply if” rules 62
12.2. Methods and functions 64
12.3. Data validation 67
Acknowledgements 69
Annex 1. System architecture 69
Annex 2. Abbreviations and acronyms 70
Annex 3. RStudio Server: writing and downloading files created during the run-time 71
Annex 4. Templates for forest inventory 73
Annex 5. Privacy Policy 78
3
1. Introduction
Arena is an Open Foris (OF) cloud platform for forest inventory data collection, utilization, analysis,
dissemination and reporting. It combines two current tools: OF Collect and OF Calc into a seamless new
application. Open Foris Arena is the main entry point for data collected in field-based inventories. It provides
a fast, easy, flexible way to set up a survey with a user-friendly interface. Arena handles multiple data types
and complex validation rules, all in a multi-language environment.
Open Foris Arena provides an online solution for field data management, allowing full customization of
inventory structure, variables and data checks. Arena promotes data quality through an integrated data entry
and data cleansing workflow. Arena contains a formal description (i.e., metadata) of the types of variables,
classifications and coding schemes used by the inventory. Older OF Collect surveys and data can also be
imported into Arena.
What are the advantages of OF Arena over the original OF tools?
• No need for user installations;

• All data stored in a secure server in the cloud (hosted by Amazon Web Services, AWS);
• Data sharing and collaboration possible in a working group;
• Easier to maintain: all updates available at the same time for all users;
• No need for trained personnel to maintain the hardware and database management system.
What does OF Arena offer?
• Dynamic form designer;

• Multilingual data entry forms;
• Editor for entering complex validation rules;
• Categories and taxonomies management;
• Multiple surveys management;
• Survey templates management;
• Multi-cycle survey management;
• Import for OF Collect survey and data;
• Possibility to use multiple species lists;
• Concurrent data entry with workflow and real time updates;
• User management;
• Survey backup (export, import), and cloning;
• Dashboard with activity logs;
• Data query, cleansing, export;
• Local off-line installation and usage via docker;
• Data analysis with RStudio Server integration 1.
The user support is available via Open Foris Support Forum at https://www.openforis.support/
Tag your question as follows:
1
RStudio is available at https://www.rstudio.com/
4
2. Typical working process
OF Arena can host any type of inventory data. A typical process when working with Arena will be as follows:
● Login into the platform;

● Select a survey;
● Depending on the user role: view, input, validate, edit, or export data;
● Data analysing the data with the help of R scripts [role: Survey Administrator, Survey Editor, Data
Analyst],
● Viewing and exporting of the results and reports;
● Logging out from the service.
3. Access to Open Foris Arena
Arena platform is available at https://www.openforis-arena.org/
There are two methods to get access to Arena:
A. to work as a Survey Administrator.

You need to create a new survey, and tailor it to fill your needs.
You can also use templates to tailor your survey.
To become a Survey Administrator, go to https://www.openforis-arena.org/

and request access to the Arena platform.
5
B. To get access to an existing survey, ask for an invitation from the Survey Administrator.
When you have got access to Arena, type in your email and password. In case you have forgotten your
password, there is an option to receive a new temporary password by email.
If you are a new user, set first your User Profile (My Profile). On the upper-right side of the screen there is a
blank icon and entry to the user profile details.
Here you can set up the following details: Title, Name (i.e., username), Email, and (access) Group. In addition,
you can add an image for your user profile.
6
4. Main user interface
View on the Arena main window depends on your user role (see Chapter “Users”). With the full access rights,
the left side panel contains the following tools.
Management of survey properties, Delete a survey,

export a survey
Design or edit data entry forms
Visual view on survey hierarchy
Management of categories (i.e., code lists)
Management of taxonomic tables
Add, view, edit, delete data
Data queries, and access to data cleansing
Export all data into a Comma Separated File (CSV) file
Import Collect/Collect Mobile data
Data validation report, and access to data cleansing
Create, edit, delete data processing chains,

run RStudio
User management, invitation of new users
Link to this manual
7
5. Selecting and creating a survey
In the upper right corner, there is an access to the following functions:
My Surveys section shows a table with all accessible surveys to the user. The list contains the following
details.
Header Explanation
NAME Name of the survey
OWNER Name of survey administrator (owner)
LABEL Label for the survey
DATE CREATED Date when the survey was created
DATE LAST MODIFIED Date when the survey was edited last time
STATUS Draft: The survey is at the editing stage. It contains no data.

Published: The survey is ready to store data. It can contain input data.
Published-Draft: The survey is ‘published’, but there are unpublished changes
in its structure (i.e., changes attribute properties, new
calculation scripts).
New Survey allows a Survey Administrator to create a new survey with three different ways: 1) Create a new
survey from scratch, 2) Clone or 3) Import a survey.
About naming of a survey:
• The name should only contain lower case letters, underscores,

• No spaces,
• No special characters (#%&”?).
The entry box will automatically ignore the wrong letters.
Next, some more information on how to create a new survey.
8
Method 1: Create a new survey from scratch.

Fill in Name, Label, and choose the default language.
Next steps after creating a new survey:

* Go into Home - Edit Info and set in Description, needed Spatial Reference System(s) (SRS)
and more languages.
* Create the survey structure using the Survey Designer, test your survey and then Publish it.
Method 2: Clone a survey from an existing survey.

Fill in a new survey Name and select a survey to be cloned. Cloning will only copy the survey structure,
not the data.
Next steps after cloning the survey:

* Go into Home - Edit Info and edit survey properties as needed.
* If the survey structure needs changes, use the Survey Designer, test your survey and then
Publish it.
9
Method 3: Import a survey,

Import offers two options:
a) import from an Arena survey, or
b) import from an Open Foris Collect survey.
3a) An existing Arena survey, such as a backup file, can be imported into Arena.
Next steps after importing the survey:

* Go into Home - Edit Info and edit survey properties if needed.
* If the survey structure needs changes, use the Survey Designer, test your survey and then
Publish it.
3b) Open Foris Collect survey can be imported from a .collect file, or a .collect-backup file containing
also data. In the latter case, both survey and data will be imported. Note that after importing you
should view the Collect Import Report at the Home section. In addition, check out all the
tables/forms’ and attributes’ properties that they are in order.
Next steps after importing the survey:

* Go into Home - Edit Info and edit survey properties as needed.
* Use the Survey Designer to modify the user-interface (as location and size of text boxes
etc.).
* Go into Home - Collect Import Report, and fix the remaining (unresolved) issues. 2
* Test your survey and then Publish it.
6. Arena Home
2
Notice that Arena does not contain all Collect’s custom functions yet. Unsupported are e.g. env:desktop(),
env:mobile().
10
The Home section contains the following functions.
“Edit info” can be also accessed by clicking the survey name
6.1. Edit survey info (metadata)
This section allows editing the metadata of the survey.
Survey metadata contains information about the following properties.
Name: Name of the survey in the database.

By changing the name, the Survey Administrator can rename the survey.
Labels: Label for a survey. For example a clear name for the survey.
View/Edit labels with other (selected) language
Descriptions: Additional information about the survey (optional).
11
Languages: Survey language(s). If more than one language is added, then all labels need to be given
by selected languages.
SRS: Spatial Reference Systems applied in the survey. Add here all SRSs which will be needed in
the data collection.
Hint: to add a new SRS, click the cursor into the input box and to see the options write
some letters of the EPSG code.
Cycles: Inventory cycle(s) and timing(s). Note: cycles cannot not overlap, so for example this data
is accepted:
6.2. Publish a survey

A draft survey needs to be published in order to make all new changes available for the survey users. These
changes can be for example changes in attributes’ properties (as new validation rules) or new calculation
scripts.
Publishing a survey will do the following changes to the survey:
● the survey will be available for data entry;

● changes applied to the survey will be visible even in data entry;
● deleted node definitions will be permanently deleted even from the records;
● modified validation rules will be evaluated again and records re-validated;
● for surveys imported from Collect: record edit will be available.
When publishing a survey, there will be the following warning at the screen.
12
6.3. Delete a survey

Only a Survey Administrator can delete a survey. Deleting removes both data and the survey structure from
the database. There is a question for confirmation, so in order to delete a survey, you need to type in the
survey name.
13
6.4. Collect Import Report

Arena uses JavaScript (JS) language in the expressions, but OF Collect uses XPath language in expressions
(as in case of Required and Validation rules). So when importing a Collect survey, all expressions need to be
converted from XPath into JS, either programmatically or by typing them manually.
After importing an OF Collect survey into Arena, the Collect Import Report table shows all expressions which
need special attention, such as possible modifications. The import process can convert the most typical XPath
expressions into JS, but not complex cases. Therefore it is really essential to fix all remaining issues before
trying to publish an imported survey.
The report table contains the following fields:
PATH: path of entity/attribute in the survey structure.
TYPE: expression type (Default value, Validation rule, Relevant if).
EXPRESSION: XPath expression in OF Collect.
APPLY IF: XPath expression in OF Collect.
MESSAGES: user-tailored message in case of Validation rule in OF Collect.
Note: you can also leave this blank, Arena can create an automatic error message.
View/Edit messages with other (selected) languages.
RESOLVED: The importing process did not do the conversion. Check all unsolved issues before
publishing your survey! Mark the issue “solved” after doing the correction.
Tag showing that the issue is solved.
14
Edit the entity’s (table/form) or attribute’s property.
The report table can be exported into a CSV file by clicking the CSV Export button. This is probably the best
way of examining what needs to be fixed in the imported survey. In this table, there is the column ‘Resolved’
where value ‘1’ shows resolved cases, and those with blank are not converted in the importing process.
Important:
Note: In OF Collect there might be a validation rule which is logically incorrect (but still working in Collect!):
a value is checked against an attribute that is given later than the current one. An example: In Collect, the
XPath validation expression is given for “Mechantable” (height) as follows:
In this case, the Collect Import Report shows this as unresolved. The reason is that in this survey “tree_height
(Height [m])” is after “Mechantable”, as seen here below. Arena cannot handle a validation expression by
using an attribute located after in the hierarchy.
15
7. Survey
The Survey section is available only for a Survey Administrator. It contains the following tools:
• Form Designer: tools for creating new data entry forms, creating and editing of tables/forms and
attributes and all their properties, and to modify the visual outlook of the forms.
• Hierarchy: Viewing of survey hierarchy and the list of attributes by entities.
• Categories: Management of categorical data (i.e. code lists).
• Taxonomies: Management of taxonomic data (i.e. species lists).
About the database terminology
Entity: Data entities are the objects of the data model such as ‘plot’ or ‘tree’. These are shown in Arena as
forms or tables. Entities are containers for attributes and relationships between objects.
Attribute: A data attribute is a unit of information inside a data entity, i.e. it is a single-value descriptor for a
data object. These are like properties of data entities: for example, an entity ‘tree’ can contain the following
attributes: species, diameter, and age.
Node (object): A node is a basic unit of a data structure, and in Arena the data structure has the shape of a
tree. A node object is represented by a single node in a tree, and it can be an element node, attribute node,
text node, or any "node type"3.
A visual presentation of a survey is shown in the following figure.
3
https://en.wikipedia.org/wiki/Node_(computer_science)
16
7.1. Form Designer

7.1.1. About the Form Designer user-interface
The Form Designer is a tool for designing the content and outlook of a survey. The Form Designer is a handy
tool to create a user-friendly interface for data management.
With the help of the Survey Designer, you can do following tasks with the forms:
Method Icon Explanation
Add a new subpage add a new entity (table/form)
Define the number of columns The default number of columns is

3, this can be changed [1 - 12]
Add a new object add a new entity or attribute
Delete an object delete an entity or attribute
Rename an object change name name of attribute

(not in case of published survey)
Add/Edit objects’ properties add/change all properties, such as

label, default value(s), validation
rules
17
Resize an object Move the cursor to the lower right

corner of the object, and then
drag to resize
Change the order of attributes Drag to an object and drop it to a

new place in the forms
Preview the survey
Move up/down Move a selected node up or down
18
7.1.2. Data types
The properties of an entity (table/form) or an attribute describe the characteristics and behavior of data
added to that object. The data type is the most important property because it determines what kind of data
the field can store. Arena supports the most common data types applied in database management systems,
and two composite data types: coordinates and taxonomic data. The data types for attributes are presented
in the following table.
Data type Icon Notes
Boolean true / false

yes / no
Code refers to categorical variables (i.e., code lists).

Read more at Chapter 7.4 (“Categories”)
Coordinate allows to enter geographical coordinates
Date entered in dd/mm/yyyy format
Time entered in hh:mm format
File allows uploading a file (e.g. photo, audio file, video, document, etc.)
Integer
Numeric
Default number of decimal digits: 6
Taxon Read more at Chapter 7.5 (“Taxonomies”)
Text allows to add free text
Note: OF Collect data type “range” (two Integer variables are created: from, to) is not supported.
Note 2: Conversion between the data types is not possible, yet. If you need to change a variable (attribute)
from Integer to Numeric, then you need to create a new variable and delete the old one. However, it is not
recommended to delete a variable if the survey is published and it contains data.
19
7.1.3. Description of properties

The object's data type determines which properties that you can set. Each data type can contain several
properties which are expressed as parameters. Some properties are common for all types, while others are
unique to a specific type. Below is a list of properties and their explanations.
Used to give the basic properties of the tables/forms and attributes.

Entity (table/form) or attribute name in lowercase letters. Should be quite short
and simple as functions within the survey use this name.
Name
For naming of entities and attributes in a survey for a forest inventory, read more
about “Naming of entities, attributes and variables” at openforis.org/materials
Type Data type
Label Label
Free text description (optional). There will be an info icon next to the label, as
follows:
Description
Label value
only for showing boolean data attribute
Max number of decimal
Number of decimal digits for a numeric data attribute
digits
Category Category name for a categorical data attribute
Parent Code Parent category (attribute) name for hierarchical categorical data attribute
Display As
only for categorical data attribute
Text transform
only for a text data attribute
Taxonomy Species list name (only for taxonomic data attribute)
Key If checked, this attribute serves as an unique identifier

Multiple Allows multiple entries for this attribute
- Min count Fixed minimum number of entries allowed
- Max count Fixed maximum number of entries allowed
Max. file size (Mb) Max. size of file to be uploaded. Only valid for a file data attribute.
File type
Only valid for a file data attribute
If the survey contains more than one cycle, an attribute can

Cycles belong to one specific cycle, or to selected cycles. Attribute’s properties (e.g.
name, label) are the same over the selected cycles, but the position on the form
may vary.
20
Used to add default entry values, and conditions when the table/form or attribute
is applicable.
Read Only If checked, the entry can only get the default value (as from an expression)
Default values:
Expression that creates the attribute’s value. This can be a constant value or any
Expression
valid expression. See more about expressions in Chapter “Expressions and
expression editor” and “Examples of Expressions”.
Apply if
Condition, when the expression is valid.
Relevant if Function that determines under what conditions the field is applicable
Used to automatically flag wrong entries during data entry. Using checks greatly
minimizes data entry mistakes and facilitates data cleansing.
Required If checked, the field is required
Checks that the entered values is unique (not repeated) within a specified group
Unique
of values
Code list Select a code list already created or create one
If checked, the input field won't be editable and the value will be generated at
Calculated
runtime according to the specified Default Value
Error - blocks the data entry user from submitting the record to data cleansing
Severity Warning - assigns a warning flag to the record but does not prevent submission to
data cleansing
Error messages Message to be displayed to flag error/warning (see an example below)
Apply if Allows to specify when the check is applicable (see an example below)
Expression Expression that defines the logic of the check
7.1.4. Units of measurements

Arena does not contain a property to set in units for numerical attributes, nor automatic conversion between
the units. It is therefore recommended to add information about the unit into the attribute’s label text, such
as “Diameter [cm]”, ”Area [ha]”, etc.
7.1.5. Summary on survey schema
The Schema Summary is an exported CSV file showing a summary about the schema. It contains the list with
all entities and attributes, data types, labels, selected properties (key, readOnly, applyIf, required, validations)
and UUID (used by the database management system).
Summary report can be exported by clicking the button. An example of a schema

summary report is presented below.
21
Note that the exported file is in Unicode (UTF-8)4.
4
https://stackoverflow.com/questions/43307776/how-to-open-a-text-file-with-excel-in-utf-8-encoding
22
7.2. Expressions and expression editor
Expressions are used to determine a value. The resulting value is usually one of various primitive types, such
as numerical, string, boolean, complex data type or other types.
Arena uses the JavaScript Math object that allows you to perform mathematical tasks on numbers. Math is
a built-in object that has properties and methods for mathematical constants and functions. See the full list
of Math methods here.
For example, constants:

Math.Pi = approximately 3.14159
Math.E = approximately 2.718
and static methods:
Math.pow(x, y) Returns base x to the exponent power y

Math.pow(2,3) = 8
Math.round(x) Returns the value of the number x rounded to the nearest integer
Math.round(9.345) = 9
Strings are useful for holding data that can be represented in text form (see link to the String object). In
JavaScript, a string is a sequence of characters enclosed in single or double quotes, and single or double
quotes are the same thing. Some of the most-used operations on strings are to check their length, to build
and concatenate them using the + and += string operators, checking for the existence or location of substrings
with the indexOf() method, or extracting substrings with the substring() method.
For example:
“Sri” + “ “ + “Lanka” = “Sri Lanka”
aString= “Vienna”;
aString.substr(0, 4) = “Vien”
aString.length =6
aString.indexOf(“nna”) = 3, aString.indexOf(“TX”) = -1 (not found)
Similarly, Javascript objects Number, Boolean, Date, and Array can be used in the expressions.
Read more about expressions in Chapter “Examples of Expressions”.
23
Examples of the expression editor
Default value: Contant (value)
Default land use is Crop Land (code “2”) Tree dbh measurement point (tree_dbh_point = 1.30)
Apply if; Relevant if: cluster_accessibility needs to be accessible (code “0”).
Advanced editor
Advanced expression editor allows you to write Javascript clauses.
An expression to compute tree cross-cutting area (in cm2).
Pressing Ctrl+Space keys allows you to browse through the list of attributes and add them into the
expression.
24
Here is an example of a rather complex expression, where the tree top height is either measured directly, or
computed from angle measurements.
The command buttons work as follows:
Quit from Advanced Expression editor mode.
Apply the expression (i.e., save it)
Clear the expression (i.e., delete it)
25
7.3. Hierarchy
In the Hierarchy section you can view a tree diagram that displays the hierarchical structure of your data. The
survey can contain multiple hierarchies, which are also each presented as one or more levels in the diagram.
The diagram can also be expanded and collapsed with button.
In our example, in the next chart we have a survey for forest inventory and the nodes from all three top
levels are now displayed by labels.
When a node is selected, the application shows a list of all attributes and child entities of the selected node.
26
In the lower right corner, there is a button to switch the view between labels and names. The list of “bamboo”
attributes shown as names looks as follows.
Show the diagram with names.
Show the diagram with labels.
There is a button to get a dropdown list of all nodes, and the attribute list can also be filtered by
the data types.
27
7.4. Categories
This tool is used to define lists of coded information that will be used throughout the survey to provide
options for specific fields during the data entry, data processing and reporting phases. If the user selects one
of the pre-filled templates, several code lists are loaded automatically. They include codified lists to define,
for example, accessibility, land use classes, ownership etc. These fields are set up in accordance to pre-
defined classification schemes however the user is free to add, remove or modify them. Code lists can be
used to classify a wide range of attributes such as administrative levels, personnel, topographic elements and
many more.
There can be two types of code lists: flat or hierarchical tables. A flat table contains only one level with two
columns: code and label. A hierarchical code list can be used - for example - for storing data by administrative
units (e.g., province, district, communities).
Adding a new category (i.e., code list)
28
New code lists can be added in two ways: "manually" or by importing a table in CSV format.
To add a new code list click on the button. Then add the Category name.
The category names should be unique. If the category name exists, there will be a warning, as follows.
To start entering codes manually, fill in Level 1 data, as follows.
When ready, click the small arrow button .
Note: in case of a flat table, Level 1 name plays no role. You can always keep it as the default name “level_1”.
A quicker option to create a new code list is to import them using a CSV file. The file should be in Unicode
(UTF-8) format.
This is the format of a CSV file for a flat table. If the survey contains just one language, then the file contains
two columns: level_1_code, level_1_[language]
29
If the survey contains multiple languages, then the labels need to be given by the languages as follows.
Names for the levels are only meaningful in case of hierarchical lists. This is an example of an administrative
list with three levels: province, district, and llg.
30
It is highly recommended to use CSV import when creating or updating a hierarchical list. The format of an
input file is as follows5.
Once a code list has been created, click on button.
Note: In OF Collect there can be a Specify field joined to a category, but in OF Arena there needs to be an
additional text attribute to store this extra data. This method can be used for example to specify unlisted
value(s) in the data entry.
In order to keep a separate record of the code list, it is suggested to Export the code list by clicking the CSV
Export button. This will automatically generate and download a CSV file.
While the manual process for adding code lists is perfectly legitimate and can be used for simple lists, for
more complex lists (e.g. list that have many items or with a hierarchical structure) it is strongly recommended
to prepare them in advance and upload them into Arena by clicking the CSV Import button.
5
Note: The table format is different from OF Collect.
31
Categories as lookup tables
Categories can also be used to import extra properties for categories, so they can also work as lookup tables.
This ancillary data can be retrieved from other sources, as from GIS, and imported then into Arena.
Extra properties are ancillary information that can be automatically added to the data with the help of
‘categoryItemProp’ function (see more in Chapter 136). In addition, in the data analysis, new categorical
variables can be created and then joined with a category table7. These variables can be used for data
aggregation, reporting or just for data processing purposes.
One survey can contain several lookup tables, if needed.
The next image shows hierarchical data in a CSV file. This can be used to import ancillary data for clusters
(level1) and plots (level2).
Currently, the extra properties can contain only the following type of data: text, numeric and geometry point.
In case of geometry point (i.e., coordinates), the spatial reference system (SRS) must be preset into the survey
(see Home section in this manual). The format of coordinate data is as follows:
SRID=EPSG:4326;POINT(X Y)
e.g. SRID=EPSG:4326;POINT(155.68 -1.48)
The best method of getting this type of ancillary data table into Arena is to create the table in MS Excel (or
equal), save it as CSV file and then import it. While importing, Arena asks to set the data type for each column
(the default is ‘text’).
6
In OF Collect this type of table is called “Sampling Point Data”, but in Arena this is a general concept and
there is no fixed name for such a table.
7
Only flat categorical tables can be used in the data analysis phase.
32
33
7.5. Taxonomies
This section allows the user to add one or more species lists by uploading a csv format file. The list should
contain all the taxonomic species that the user will select from during data entry. Species lists should be as
comprehensive as possible and should be created using all resources available in the country: local or global
databases, taxonomical books, experts’ knowledge etc. For security reasons it will not be possible to add
species during data entry. Instead, additional species should be added to the csv file (by a survey
administrator) and the updated species list uploaded to Arena.
Adding a Species list:

The species list (CSV file) file should be prepared in advance following the formatting requirements indicated
below.
The required columns are:
● code: alphanumeric unique identifier code associated to the species (required),
● family: family name of the species (optional),
● genus: genus of the species (optional),
● scientific_name: latin name of the species (genus + [optionally] species name + [optionally]
subspecies name e.g. Pinus spp. or Pinus radiata),
● lat: synonym(s) (optional)8,
● vernacular name, like local name or a timber trade name (optional).
An example of valid species list:
8
In an imported OF Collect survey, column “synonym” is shown as ‘lat’ in Arena.
34
Optionally the user can specify other columns, such as the vernacular names of the species using the language
code (in 3 characters ISO-639-2 format, e.g. 'swa' for Swahili, 'eng' for English) as header of these columns.
Multiple values are allowed for vernacular names and they need to be separated with a slash ( / ) character.
Note: one species name (in scientific_name, synonyms or in vernacular name columns) can exist only once
in the table. So each name should have a unique species code.
In order to add a new taxon list, specify a name for the list. Then upload the CSV file, and click Done when
ready. The screen will now show the records present in the species list. Species lists can also be renamed,
deleted or exported. If needed, additional species lists can be created and uploaded in the same manner.
There are two species names automatically added to your list by the system: Unknown (UNK) and Unlisted
(UNL). Avoid entering these same names and codes into the survey.
35
8. Templates
8.1. Using a template file
Templates are surveys which contain an easy way to start designing a new survey. They are tested surveys
which will fit to specific purposes, such as forest inventory data collecting. They can be cloned when creating
a new survey.
More about the templates:
● Only the Survey Administrator can clone a template and modify it to fit into the local forest inventory
design.
● It is easier to delete entities (tables/forms) and attributes than create them. Therefore there are
more entities and attributes in these templates than needed!
● Survey labels are stored with multiple languages. All labels can still be edited as needed, and new
language(s) can be added.
In July 2021, there are the following four templates shown in the next table in Arena (see Annex 4 containing
screenshots of these templates).
# Name of template Purpose Language(s)
1 template_forest_inventory_b Typical forest attributes for a forest inventory case. English,

This is a template with the following structure: French,
cluster (or tract/transect)-plot-child entities (several) - Spanish
'canopy_cover' is an assessment at the 'plot' level
-'stratum' can be a property of 'cluster' or 'plot'
2 template_forest_inventory_c Typical forest attributes for a forest inventory case. English,

Template with the following structure: French,
cluster (or tract/transect)-plot-subplot (or stand/section)- Spanish
child entities (several)
3 template_forest_inventory_d Typical forest attributes for a forest inventory case. English,

Template structure: French,
plot-subplot (or stand/section)-child entities (several) Spanish
-'canopy_cover' is under 'plot' level
4 template_forest_inventory_e Typical forest attributes for a forest inventory case. English,

This is a template with the following structure: French,
plot-child entities (several) Spanish
More templates will be added into Arena by FAO by the end of 2021.
36
When you need to create a new survey using a template, follow these steps:
1) Goto New Survey at the upper-right corner, select CLONE and a Template can be selected from the
top of the list, as follows:
2) Give a new name to your survey, and click the CREATE SURVEY button.
3) Select and edit survey properties. You can still change the survey name here.
You can also delete all unneeded languages, and add the required spatial reference systems into the
survey.
4) Go into the Form Designer, and edit the survey as needed. You can delete the unneeded entities
(tables/forms) and attributes, and add new ones into the pages.
In templates, there are typically more entities and attributes than needed, because it is faster to
delete the extra ones than to add new attributes.
5) Test your survey with Preview.

6) When ready, Publish the survey.
7) Goto USERS and invite users to get access to your survey (see more at the chapter “Users and Access
to Arena”).
8.2. Getting a new template into Arena
Currently, only a System Administrator can add new templates. If you are a Survey Administrator and you
want to offer a new template into Arena or improve an existing one, please contact the Arena development
37
team by an email: [email protected], write into the Topic field: “Suggested survey to Arena
template”.
A new should be an existing, published and tested survey in Arena. It should be generic for a certain data
collection purpose. As stated above in the previous section, a good template can contain “more attributes”
than needed, because it will be easier and faster for other Survey Administrators to delete the extra
(unneeded) ones than to add new attributes in the Form Designer.
9. Data
9.1. What are the data entry stages?
Arena implements a workflow which divides data processing into three steps (or stages): 1) data entry, 2)
data cleansing, and 3) data analysis.
1) Data entry stage

● Data are entered into the system exactly as they appear on paper field forms.
● They are neither interpreted nor corrected during this phase.
● Invalid values (those marked as “error”) must be checked against the field forms. If the
value was copied correctly, the value should be manually accepted. If it was copied
incorrectly, the value should be entered as it appears on the field forms.
● Once all errors are either resolved or confirmed, the data entry clerk submits the record for
data cleansing. Before entering the cleansing phase, a copy is made and marked read-only.
No further changes may be made to this record by data entry staff (unless the record is
returned by data cleansing staff).
2) Data cleansing stage

● Experts with knowledge of field conditions and data work with a copy of the data entered in
step 1 to correct or remove invalid values.
Note: “Data entry” level users cannot not edit the data which is at the cleansing stage.
38
● If the data cleansing expert deems that the data entry task was not completed or that the
record contains too many errors, the record may be returned to phase 1 (entry) for additional
changes.
● Once all data errors are resolved, the record may then be submitted for data analysis. This
locks the record so that no further changes may be made.
3) Data analysis stage

● Records marked for data analysis are ready for analysis.
● If during analysis data are deemed incomplete or incorrect, the record may be rejected and
sent back for further cleansing. Once updated and resubmitted, the record may once again
be available for calculation and analysis.
9.2. Adding and editing records
The Records section is for entering, editing and viewing data. The main entry view for the Records section
contains a list of all entries (as root level) shown with some metadata: value of key field, Date when created,
Date when modified, Owner, Step, number of Errors, and number of Warnings.
The steps (=stages) are coded as follows:

1: Data entry stage, 2: Data validation stage, 3: Data analysis stage.
Inputting data is straightforward. You will see all tables/forms at the left side panel, and data entry form in
the main window at the right side. Start always entering data at the highest hierarchical level. For example,
39
if you want to save forest inventory data where the structure is “cluster-plot-tree”, input the cluster level
data first, then the plot level etc. This guarantees the consistency of the stored data.
Arena does not lock the records (at data entry stages 1 and 2): users can work with the same data set, even
edit the same record simultaneously. All records are locked only when data is submitted to stage 3 (Data
Analysis).
Start adding a new records by clicking button. The program will open a data entry form. While
entering the data, all data are automatically written into the database, i.e. there is no ADD-button!
All items that are set as “required” are marked with a red symbol as long the input field stays blank. The
red label text and the red symbol can also indicate that there can be an error in the data item.
In case of a multiple-entry table/form, such as tree data, the new record can be added by clicking the
button next to the table/form’s name.
There are two options how to see the entities and attribute identifiers:
40
entity (table/form) or attribute name is shown,
entity or attribute label is shown.
When working with forms that belong to lower level entities, there is a text in the upper left corner showing
the position of the record in the survey hierarchy, as follows:
Entering of species data can be handled so that starting typing in the first letters of the species name, or a
code. Then a dropdown menu will emerge and you can pick up the correct name as shown in the next image.
There are two species names automatically added by the system: Unknown (UNK) and Unlisted (UNL). In
order to enter one of these, type ‘un’ into the species name input box.
Column width in tables is fixed in Arena version 1.0, but this limitation will be improved in the coming version.
41
9.3. Deleting a record
If you need to delete a record, then click it and you will get into the data editing mode. Then click on
button. This button is not visible if the data is at the analysis stage (Step 3).
A row of a table can be deleted as follows: browse to the last column of a row. There you will see a
trashbox icon. Click that and message box will appear:
You can click OK if you are sure. But be aware: there is no UNDO function in the system!
42
9.4. Data Explorer and aggregating data
Data Explorer is a tool for viewing the data in the tabular format. You can view both input data and
(computed) result variables in the same table. Data can be viewed in multiple ways (such as filtered and/or
sorted), and it can be exported into a CSV file. In the EDIT MODE, data can also be directly edited at this view.
Data Explorer can be used to aggregate data. This means that it can work as a reporting tool in “Aggregate
Mode”.
All data in the view can be exported into a CSV file.
The current version allows to view and export the computed result variables in the Data Explorer view (see
Chapter 9.4). Similarly as imputed data attributes, computed result variables can be selected into the view,
as below.
43
Data can be also aggregated to higher levels of the hierarchy. For example, tree result variables, such as “tree
volume” can be aggregated to a plot level, or any upper level.
An example how see the aggregates:
1) select your table/form to report measures
2) Click (Aggregate mode) button to be yellow.

3) Select the Dimensions to be reported. In this case Cluster no, Plot ID:
44
4) Select the measure(s) to be reported.
5) In the table view, we can click here the icon and change the aggregate
function.
45
and we can see the number of cases (Count) and the average DBH.
6) Custom aggregate functions can also be added. The aggregation uses the Structured Query Language
(SQL) expressions because this is the fastest way of processing database data via Arena user-
interface.
After clicking SAVE, we can see the list of custom aggregate functions as follows:
The reported custom aggregates need to be selected in order to see them in the report table.
7) click close button
46
8) Data view can now be exported a CSV file and download to the local machine.
9.5. Export all data into CSV
All data (excluding file type data) of the current survey can be exported into a zip file that contains several
CSV files. The zip file contains all attributes grouped by entities. In the left side panel click on EXPORT and
click the button to execute the data export.
After exporting the data into the server, still download it by clicking the button.
The next image shows an exported file containing forest inventory data.
47
Currently, data is exported from its current (highest) level 9.
9.5. Import data from Collect/Collect Mobile file
If a survey is created in OF Collect, and this survey is imported into Arena and published, data can also be
imported into the Arena (later). This enables collection of data using OF Collect Mobile in data collection.
Data to be imported must be in .collect-data format.
Note: The checkbox “delete all records before import” means that all records in the target survey will be
deleted. Be cautious while using this selection!
Selection “Force import from another survey” allows importing data from a collect-data file, which may have
different survey name in Collect than in Arena, but the same schema (i.e. schemas can match).
9
In the later Arena version there will be a selection that only Entry, Cleansing or Analysis level data can be exported.
48
9.6. Validation report
Errors in data can be detected by several means. While editing the data in Data Records, there can be an
error message indicating that there is something wrong in the data. However, there is no
easy way to find the erroneous data in the Data Records. So for searching and browsing the erroneous data,
we should use the Validation Report tool.
The data validation report is a table that is created by running through all data validation checks in the survey.
It is essential to run this report and fix all errors in the data before the data enters the Analysis phase. Note:
if your data is already at the Analysis step , you cannot not edit the records. You need to
submit the record back to Step 2.
The validation report can look as follows:
The validation report shows all records that have issues, either ‘Warning’ or ‘Error’. The Error message will
be automatically generated, if the custom “Error Message” is left blank in the survey designing phase.
The erroneous records can be directly accessed and edited from the Validation Report view.
49
10. Analysis
10.1. Creating a processing chain
The data processing in Arena is handled with the help of R language script. Each survey has unique scripts,
and the Survey Administrator can add and modify the scripts. The data processing can be run using RStudio
in the cloud, or locally with R and RStudio installed in the personal machine.
In Arena version 1.0, the data reporting (aggregating) part is still under development and the full
implementation will be ready by the end of 2021.
Data processing can be conducted with the help of a calculation chain, which contains calculation of result
variables. We call these variables as modules in this manual. A survey can contain more than one calculation
chain, if needed.
Start creating a new calculation chain by clicking button.
Then give the label for the calculation chain, as follows.
A chain must contain at least one result attribute, so create that next. First, select the table/form which will
contain the new result variable:
50
From the above list, ‘Trees’ is selected. Then we need to select whether we give a quantitative or categorical
variable.
For example, “tree volume” to be computed is a quantitative variable.
Click the button.
Fill in the variable’s name10, label and number of decimal digits. The script can be left as it is at this point,
because it can be written later in RStudio. Then click the SAVE button, and then the BACK button.
You will see the list of results variables as follows.
Note: In the label text (C) means that this is a calculated attribute.
ACTIVE means that this variable is computed while processing the data. The variable can be also
deactivated if it is not needed but we want to keep it here.
10
If you are working with forest inventory data, please see the recommended naming approach in “Naming of
entities, attributes and variables in Collect / Calc” at http://www.openforis.org/materials/
51
Categorical data can be used for reporting (i.e. for aggregation) or in the computing chain. Add a new
categorical result variable by first clicking the entity that contains this variable. Then click the
button.
Fill in the name and label. The categorical variable needs to be linked with an existing categorical table, and
only a join with a flat category table is allowed! If the category table does not exists yet, it can be created
with the button. If the category table exists already, click the button, select the category
from the list and click the button and then the button to close the list. Then click the
and then the button.

The calculation chain now looks as follows.
Note: the order of computed variables may be really important! For example, in forest inventory case above-
ground biomass needs to be computed before computing the below-ground biomass. The order of variables
can be changed by moving the cursor on the top of the icon on the left side of the name, and drag-and-
dropping the variable to the right location.
52
When all result variables are created, the survey needs to be published. Run .
53
10.2. RStudio in programming and data processing
The R scripts can be written, debugged and run using RStudio integrated development environment (IDE) for
R. Arena offers two options how to use RStudio:
1) RStudio Server in the cloud, or
2) locally installed RStudio (in your machine).

Note: You should have package 'rstudioapi' installed.
The process of using both RStudio options goes as follows:
1) Click the RStudio button.

2) You will see this type of window (the scripts are different for the Server and local RStudio):
Then click OK.
Arena will automatically copy the initialization script to your clipboard 11.
3) Server: RStudio will start.

Local: Start RStudio on your machine. Open a tab for a new blank R script.
4) Paste (CTRL-V) the copied script into the RStudio Console window and run it. This will download all
scripts into Rstudio (from Arena’s PostgreSQL database).
5) In Files view, you will see this content
11
The initialization script is valid for 60 minutes, then it will expire.
54
arena.R = the main program (do not edit!)

/system = folder for system-generated files (do not edit!)
/user = folder for result variables (these you will edit)
Note about local RStudio: If you do not see this view, click the Files tab, and run this command in the
R Console: rstudioapi::filesPaneNavigate(getwd())
6) click file arena.R

Run the first two (2) lines of the code.
The file 001-init.R contains system initializing commands, as access to the database management
system. In Rstudio Server, it also installs a great number of packages into your RStudio session. In
local RStudio, only a few essential packages are installed (if they have not been installed already 12).
The list of all installed packages can be viewed here: [home]/system/init/init-packages.R
Running this script takes a few seconds, when a new RStudio session is opened. Next time running
this script goes faster.
The file 002-login.R opens two input boxes in order to get access to your data in the Arena
database: first type your username (email) to Arena, and then into the second inputbox your
password. For security reasons your credentials are not shown in plain text.
12
The list of packages can be found at /system/init/init-packages.R
55
After a successful login, you should get a message to the Console screen, such as
"User [email protected] successfully logged in"
7) Run the third line of the code.
source('system/003-read-data.R')
This will initialize the variables (as data frames) and download the data. See the Environment
window in RStudio.
8) Open the folder /user
This folder contains the common file for adding R scripts (as functions) that are common for all scripts
(modules) following file 004-common.R
Important notice about writing using R packages and function:
● Try to write all package loads into 004-common.R, because it will be the easiest to manage
them in one file.
● RStudio RServer is running on a Linux machine. Some packages may not run on Linux.
● While calling new packages, avoid using the ‘library’ command. Instead, use the command
‘usePackage’. This is a function, which checks whether a package is preinstalled. If not, then
it will be installed. This is the usePackage-function code (located in a system file called as
init-packages.R):
● Because (in RStudio RServer) there are a high number of (active) packages, it is better to
write the package name in the front of a function, whenever you call the function. For
example:
56
dplyr::select(), dplyr::filter(), etc.
9) All files in the folder /user and below are the ones that will require working. For working methods
with the R-scripts, please see hints in the OF Calc manual (from p. 39)13.
In the RStudio project, all data are in dataframes by entities. In addition, there are the following two
lists (of data frames): categories and taxonomies. For example: if the survey contains a code list
‘land_use’, it can be accessed as a data frame as follows: categories$land_use.
10) When all scripts are tested, saved, and can run error-free, you need to run the source code of the
main program. So select window of arena.R and run the
This will return all R scripts and write computed results data back to Arena’s database.
11) RStudio Server: After a successful run, you can close your RStudio session. Go to the Arena’s main
window, choose and terminate your RStudio connection.
Terminating the connection will release server resources to other RStudio users in the cloud.
If RStudio Server does not run:
If you see this type of error in the web browser
It means that the RStudio Server instance cannot start at this moment. In this case, wait for 5-10 minutes and
try again. This may happen in cases where there is a high number of users trying to access the system at the
same time.
External files (e.g. CSVs, graphic files)::
If you work with the Studio Server and want to create new files during the run-time, such as CSV files or
graphic files, please see the guidance at Annex 3.
13
During 2021, online video tutorials will be available on how to write scripts into Arena. Also later the templates
containing embedded R scripts will be available to facilitate the data processing part.
57
11. Users and access to Arena
Each survey is hosted by one or more Survey Administrators. A Survey Administrator can invite new users by
sending an invitation email from Arena.
In order to become a Survey Administrator, please go to www.openforis-arena.org and click on the Request
Access link:
Fill the form, send the request and wait for the request to be approved. You will receive an email with the
details on how to access Arena.
58
The users are divided into the following roles, each of them having different access rights to the tools, surveys
and data.
59
Permission Survey Survey Editor Data Analyst Data Cleanser Data Editor
Administrator
Survey Create X
Clone X
Edit own surveys X X
Delete own surveys X
Export (Arena) schema X X
Collect Import Report X X
Data Add new records (own surveys) X X X X X
Edit all records (own surveys) X X X X
Edit own records (own surveys) X X X X X
Submit record to Cleansing X X X X X
Submit record to Analysis X X X X
Access Validation tools X X X X
60
Export data to CSV X X X
Analysis Full access to analysis tools X X X
Users Invite users to own surveys X
Edit users of own surveys X
The survey administrator can invite new users to get access to OF Arena and to the current published survey. The invitation is sent to an email address.
This is an example of email to access a survey:
If people do not get an email invitation, the message might be blocked by a strict firewall filter on the recipient’s end. Ask the recipient to check their spam, junk,
and clutter folder for the invitation message.
61
12. Examples of expressions
Arena uses Javascript programming language for expressions. Because some users may be familiar with XPath language expressions used in OF Collect, the
next tables represent expressions with both these languages.
Note: In JavaScript, a string is a sequence of characters enclosed in single (‘) or double (“) quotes. The choice of quoting style is up to the programmer.
12.1. “Relevant if” and “Apply if” rules
# Rule Attribute path XPath expression Javascript

A1 Entity ‘tree’ is relevant only if plot is /cluster/plot/tree/ plot_accessibility = ’0’ plot_accessibility == “0”
accessible
A2 Attribute “stem form” is relevant is plant /cluster/plot/tree/tree_form tree_type != ’PALM’ tree_type != ”PALM”
type is not a palm
A3 Attribute “stem form” is relevant if a tree is /cluster/plot/tree/tree_form tree_status = ’LIVE’ and tree_dbh>=40 tree_status == ”LIVE” &&
living (tree_status=‘LIVE’) and DBH more or tree_dbh >= 40
equal to 40cm (tree_dbh>=40).
A4 Trees and stumps are collected in the same /cluster/plot/tree/ stump stump==true
form: Stump diameter is only recorded for tree_ stump_diameter stump=true()
stumps (i.e. boolean attribute ‘stump’ is
TRUE).
A5 Tree condition code is not “S” not( tree_condition='S' ) !( tree_condition == ”S” )
A6 Trees and stumps are collected in the same /cluster/plot/tree/tree_ not(stump) and !stump && Number(tree_condition) > 1
form: “Causative agent” is only recorded for causativeagent number(tree_condition)>1
trees which are not healthy (numeric value

of code ‘tree_condition’ is greater than 1).
A7 Checks if an attribute is empty idm:blank(attribute_name) isEmpty(attribute_name)
idm:not-blank(attribute_name) !isEmpty(attribute_name)
Checks if an attribute is not empty
A8 Checks if X coordinate is empty /cluster/plot/plot_location isEmpty(plot_location.x)
A9 Tree top height only required for every third /cluster/plot/tree/tree_height_top tree_id mod 3 = 0 (tree_id % 3) == 0
tree
A10 Attribute is relevant if species in unlisted /cluster/plot/tree/ tree_species/@code="UNL" or tree_species.code=="UNL" ||

(UNL) or or unknown (UNK) tree_species/@code="UNK" tree_species.code=="UNK"
A11 Desktop/Mobile device env:desktop() -Not supported yet

env:mobile()
63
12.2. Methods and functions
# Method / Function Attribute path XPath expression Javascript

B1 moves the "context" to the upper level parent() parent(node_name)
B2 access of entities and attributes using index /cluster/plot/tree/ plot[1].tree[2]

Note: indexing starts from 0
B3 access members of composite attributes:

● coordinate - location/@x, location/@y - location.x, location.y, location.srs
- tree_species/@code, - tree_species.code,
● taxon tree_species/@scientific_name, tree_species.scientificName,
tree_species/@vernacular_name tree_species.vernacularName
● file
- my_file. fileName, my_file.fileSize
● date
- my_date/@year, my_date/@month, - my_date.year, my_date.month, my_date.day
● time my_date/@day
- my_time/@hour, my_time/@minute - my_time.hour, my_time.minute
B4 Get tree number automatically (from current /cluster/plot/tree/tree_no math:max(parent()/tree/tree_no + 1 Math.max(plot.tree.tree_no) + 1

maximum tree_no)
B5 Get the index for a multiple entity idm:position() index(node_name) + 1
example: multiple entity ‘tree’ and e.g. index(tree) + 1

attribute to edit is ‘tree_no’
index(tree) Note: index starts from zero (0)
64
B6 Get DBH of from previous tree in a table /cluster/plot/tree/tree_dbh plot.tree[index(tree) -1].tree_dbh
B7 Get inputted value from another table from Source table: seasonal_calendar parent()/seasonal_calendar[idm:positi seasonal_calendar[index(product_unit)].seaso
one of its field (seasonal_product), with the Source attribute: on($context)]/seasonal_product nal_product
same row position seasonal_product
Target table: product_unit
Target attribute:product_name
/community/product_unit/product_
name
B8 Boolean attribute: get default value TRUE / FALSE true / false

true() / false()
B9 Get date automatically idm:currentDate() now()
B10 Get time automatically idm:currentTime() now()
B11 Number of records in a table node_name.length

e.g. tree.length, plot.length
B12 Concatenate text strings concat(txt_attr1, txt_attr2) txt_attr1 + text_attr2

More about string functions here
B13 Calculate slope percent from degrees /cluster/plot/slope/slope_percent math:tan( slope_deg * 3.141592654 Math.tan( slope_deg * 3.141592654 / 180) *
div 180) * 100 100
B14 Area of circular plot, radius 18m 3.141592 * math:pow(18,2)) Math.PI * 18**2
65
B15 Region name is given as an Extra Property in /cluster/region idm:samplingPointData(‘region_label’, categoryItemProp('sampling_point_data',

the category table ‘sampling_point_data’ cluster_id) ‘region_label', cluster_id)
and we want to get this name automatically
after the cluster id is entered.
B16 Land use in 2013 is given as an Extra /cluster/plot/land_use idm:samplingPointData('land_use_201 categoryItemProp('sampling_point_data',

Property in the category table 3', parent()/plot_id) 'land_use_2013', cluster_id, plot_id)
‘sampling_point_data’ and we want to get
this text automatically for a plot after the
cluster id and plot_id are entered.
B17 Display the desired column from the species idm:speciesListData("SPECIES_LIST_NA (not implemented yet)
list ME", "column_list",
TAXON_ATTRIBUTE_NAME)
B18 Calculate cumulative sum of basal area: /cluster/plot/tree/tree_cum_ba sum(parent()/tree[tree_num < (not implemented yet)
sum the basal area of the inserted trees & $this/parent()/tree_num]/tree_basal_
a calculated attribute inside of it area)
"tree_num" with the position of the
tree, i.e in XPath. idm:position()
B19 Expected plot center location from /cluster/plot/expected_plot_locatio idm:samplingPointCoordinate(parent() categoryItemProp('sampling_point_data',

Sampling Point Data n /cluster_id, plot_id) 'location', cluster_id, plot_id)
B20 Distance from actual to expected plot center /cluster/plot/expected_plot_loc_dist idm:distance(plot_location, distance(plot_location,
ance expected_plot_location) expected_plot_location)
B21 Compute the mean canopy closure (%) using /cluster/plot/mean_canopy_percent 100 - 1.04 * sum( 100 - 1.04 * (
a densiometer with 24 squares, four parent()/canopy_cover/canopy ) plot.canopy_cover[0].canopy +
plot.canopy_cover[1].canopy +
measurements in a plot Explanation: 24 squares x 4 plots = 96, plot.canopy_cover[2].canopy +
and 96 x 1.04 approx. = 100. plot.canopy_cover[3].canopy +
Attribute ‘canopy’ is given as number plot.canopy_cover[4].canopy
of squares that are under the direct )
sunlight (i.e. not shaded by trees)
66
12.3. Data validation
# Rule Attribute path XPath expression Javascript

C1 Nested sample plot: /cluster/plot/tree/tree_dbh $this >= 5 and tree_distance <= 3 tree_dbh >= 5 && tree_distance <= 3
1) Tree min. diameter of 5 cm collected in
3m plot radius. $this >= 10 and tree_distance <= 7 tree_dbh >= 10 && tree_distance <= 7
2) Tree min. diameter of 10 cm collected in
7m plot radius.
C2 Bole height rule is this: /cluster/plot/tree/tree_height_bole

- Should be always less or equal to tree top tree_height_bole <= tree_height_top tree_height_bole <= tree_height_top
height (tree_height_top) if top height is $this < 30 tree_height_bole < 30
given, Apply when: Apply if:
- Should be always less than 30 m tree_height_top !isEmpty(tree_height_top)
C3 Plot elevation must be between 0 and /cluster/plot/details/plot_elevation 0 <= plot_elevation <= 4000 0 <= plot_elevation && plot_elevation <=
4000 m 4000
C4 Date must be current or earlier than current /cluster/start_date start_date <= idm:currentDate() start_date <= now()
date
C5 Working hours for the survey should be /cluster/start_time 0600 < start_time <= 1900 "06:00" < start_time < "19:00"
from 06:00 to 19:00
C6 End time should be after start time /cluster/end_time end_time >= start_time end_time >= start_time
(Here we assume that start_time and end_time are
under the same entity)
C7 Tree number must be greater than zero /cluster/plot/tree/tree_no 0 < tree_no 0 < tree_no
67
C8 angle must be between 0 (inclusive) and /cluster/plot/tree/tree_azimuth 0 <= tree_azimuth < 360 0 <= tree_azimuth && tree_azimuth < 360
360 (exclusive)
C9 Tree distance in a plot must be positive /cluster/plot/tree/tree_distance 0 <= tree_distance 0 <= tree_distance
C10 Y-coordinate of plot location must be /cluster/plot/plot_measured_location plot_measured_location/@y<0 plot_measured_location.y<0

negative
C11 Distance between two points must be less /cluster/plot/plot_measured_location distance(plot_measured_location,

than 50m plot_centre_location ) <= 50
/cluster/plot/plot_centre_location
68
Acknowledgements
The Open Foris Arena platform has been built with the support of the Government of Norway and the UN-
REDD Programme through the Food and Agriculture Organization of the United Nations (FAO).
The deepest thanks to the developers of the system: Cosimo Togna, Stefano Ricci, Ramiro Blazquez-Gonzalez,
Lauri Vesa, Miró Sorja, Stefano Giaccio and Elias Kunnas. The Arena logo was designed by Jérôme Agostini.
The other contributors in the development have been Rebecca Tavani, Inge Jonckheere, Julian Fox and Anssi
Pekkarinen.
Annex 1. System architecture
OF Arena is built with JavaScript programming language and the system is based on the following
components:
• Static front-end in React.js 17.x
• Back-end in Node.js 14.x
• Database Management System: PostgreSQL 10.x/11.x
• Amazon Web Services (AWS),
• System front-end and back-end will communicate via Web Socket connection, and the OF
authentication system uses local user storage. OF sends notifications via email.
• External data: OF users can upload files into the system,
• Open Foris integrates with RStudio server.
OF Arena uses cookies, so they should be allowed in the web browser. The system is tested with the following
web browsers: Google Chrome (recommended), Windows Edge, Opera and Safari.
Annex 2. Abbreviations and acronyms
AWS Amazon Web Services
CSV Comma Separated File
EPSG EPSG Geodetic Parameter Dataset (also EPSG registry)
FAO Food and Agriculture Organization of the United Nations
ID Identifier
JS Javascript
NA Not available (missing data)
OF Open Foris
R Programming language
SQL Structured Query Language
SRS Spatial reference system
70
Annex 3. RStudio Server: writing and downloading files created during the
run-time
Because RStudio Server works on a remote server, getting files, such as CSV files or graphic files, created by
the R scripts from the server to the user’s machine requires special methods. Here we go through how to do
this.
1) Write this script into 004-common.R:
# define a folder for output files

user_file_path <- './user_export/'
# create a folder for files to be exported

if (!dir.exists( user_file_path )) dir.create( user_file_path )
Optionally, you can also use a function to add all “user’s files” into a zip file (arena_R_export.zip)
which can be downloaded (after running the project files). Add also this script into 004-common.R
(after the script above):
zip_user_files <- function(tFolder) {

#delete zip if it exists (i.e., file to be downloaded)
fn <- paste0( tFolder, "arena_R_export.zip ")
if (file.exists(fn)) {
#Delete file if it exists
file.remove(fn)
}
# check if any files to be zipped

f <- list.files(tFolder, all.files=TRUE, recursive=TRUE, full.names=FALSE)
if (length(f) > 0) {
zip::zip("arena_R_export.zip", f, recurse=TRUE , root=tFolder, include_directories = TRUE,
mode = "mirror")
}
}
Note: add script

zip_user_files( user_file_path )
into the very last calculation module.
2) in the part where you need to write something into a CSV file, use this type of command line
write.csv(my_DF, paste0( user_file_path, "test.csv" ), row.names = FALSE)
71
3) To download the files from the server, there are two methods:
a) using RStudio’s EXPORT tool (this is easier),
b) or by R coding.
a) RStudio’s EXPORT tool:
In the Files pane, More menu, there is an Export… option:
b) Coding method to export the files from the server:
file_list = list.files(path=user_file_path, pattern="*.csv")

for (i in seq_along(file_list)) {
export_filename = file_list[[i]]
# create a path for file to export

my_export_file_path <- paste0(user_file_path, export_filename)
# make a pause before exporting the next file, otherwise there can be a pop-up warning
if (i > 1) {
cat('*** PRESS ENTER HERE')
readLines(stdin(), 1)
}
# export to local disk using browser's capabilities

browseURL(my_export_file_path)
}
72
Annex 4. Templates for forest inventory
The following tables screenshots of templates in OF Collect and Arena.
template_forest_inventory_b
Template B:
cluster – plot – several entities
73
test
template_forest_inventory_c
Template C:
cluster – plot – subplot – several entities
74
template_forest_inventory_d
Template D:
plot – subplot –several entities
75
template_forest_inventory_e
Template E:
plot – several entities
76
77
Annex 5. Privacy Policy
Effective date: May 1, 2021
Food and Agriculture Organization of the United Nations ("FAO", "us", "we", or "our") operates the Open
Foris Arena website (the "Service").
This page informs you of our policies regarding the collection, use, and disclosure of personal data when
you use our Service and the choices you have associated with that data. This Privacy Policy is powered
by FreePrivacyPolicy.com.
We use your data to provide and improve the Service. By using the Service, you agree to the collection and
use of information in accordance with this policy. Unless otherwise defined in this Privacy Policy, terms
used in this Privacy Policy have the same meanings as in our Terms and Conditions, accessible from
https://www.openforis-arena.org/
Information Collection and Use
We collect several different types of information for various purposes to provide and improve our Service
to you.
Types of Data Collected
Personal Data
While using our Service, we may ask you to provide us with certain personally identifiable information that
can be used to contact or identify you ("Personal Data"). Personally identifiable information may include,
but is not limited to:
● Email address
● First name and last name
● Associated organization
● Title
● Cookies and Usage Data
Usage Data
We may also collect information on how the Service is accessed and used ("Usage Data"). This Usage Data
may include information such as your computer's Internet Protocol address (e.g. IP address), browser type,
browser version, the pages of our Service that you visit, the time and date of your visit, the time spent on
those pages, unique device identifiers and other diagnostic data.
Tracking & Cookies Data
We use cookies and similar tracking technologies to track the activity on our Service and hold certain
information.
78
Cookies are files with a small amount of data which may include an anonymous unique identifier. Cookies
are sent to your browser from a website and stored on your device. Tracking technologies also used are
beacons, tags, and scripts to collect and track information and to improve and analyze our Service.
You can instruct your browser to refuse all cookies or to indicate when a cookie is being sent. However, if
you do not accept cookies, you may not be able to use some portions of our Service.
Examples of Cookies we use:
● Session Cookies. We use Session Cookies to operate our Service.

● Preference Cookies. We use Preference Cookies to remember your preferences and various
settings.
● Security Cookies. We use Security Cookies for security purposes.
Use of Data
We use the collected data for various purposes:
● To provide and maintain the Service

● To notify you about changes to our Service
● To allow you to participate in interactive features of our Service when you choose to do so
● To provide customer care and support
● To provide analysis or valuable information so that we can improve the Service
● To monitor the usage of the Service
● To detect, prevent and address technical issues
Transfer of Data
Your information, including Personal Data, may be transferred to and maintained on computers located
outside of your state, province, country or other governmental jurisdiction where the data protection laws
may differ from those of your jurisdiction.
Your consent to this Privacy Policy followed by your submission of such information represents your
agreement to that transfer.
We will take all steps reasonably necessary to ensure that your data is treated securely and in accordance
with this Privacy Policy and no transfer of your Personal Data will take place to an organization or a country
unless there are adequate controls in place including the security of your data and other personal
information.
Disclosure of Data
Legal Requirements
We may disclose your Personal Data in the good faith belief that such action is necessary to:
● To comply with a legal obligation

● To protect and defend the rights or property of FAO
● To prevent or investigate possible wrongdoing in connection with the Service
● To protect the personal safety of users of the Service or the public
● To protect against legal liability
79
Security of Data
The security of your data is important to us, but remember that no method of transmission over the
Internet, or method of electronic storage is 100% secure. While we strive to use commercially acceptable
means to protect your data, we cannot guarantee its absolute security.
Service Providers
We may employ third party companies and individuals to facilitate our Service ("Service Providers"), to
provide the Service on our behalf, to perform Service-related services or to assist us in analyzing how our
Service is used.
These third parties have access to your Personal Data only to perform these tasks on our behalf and are
obligated not to disclose or use it for any other purpose.
Analytics
We use third-party Service Providers to monitor and analyze the use of our Service.
● Google Analytics
Google Analytics is a web analytics service offered by Google that tracks and reports website traffic.
Google uses the data collected to track and monitor the use of our Service. This data is shared with
other Google services. Google may use the collected data to contextualize and personalize the ads
of its own advertising network.
You can opt-out of having made your activity on the Service available to Google Analytics by
installing the Google Analytics opt-out browser add-on. The add-on prevents Google Analytics
JavaScript (ga.js, analytics.js, and dc.js) from sharing information with Google Analytics about visits
activity.
For more information on the privacy practices of Google, please visit the Google Privacy & Terms
web page: https://policies.google.com/privacy?hl=en
Links to Other Sites
Our Service may contain links to other sites that are not operated by us. If you click on a third party link,
you will be directed to that third party's site. We strongly advise you to review the Privacy Policy of every
site you visit.
We have no control over and assume no responsibility for the content, privacy policies or practices of any
third party sites or services.
Children's Privacy
Our Service does not address anyone under the age of 18 ("Children").
We do not knowingly collect personally identifiable information from anyone under the age of 18. If you
are a parent or guardian and you are aware that your Children have provided us with Personal Data, please
80
contact us. If we become aware that we have collected Personal Data from children without verification of
parental consent, we take steps to remove that information from our servers.
Changes to this Privacy Policy
We may update our Privacy Policy from time to time. We will notify you of any changes by posting the new
Privacy Policy on this page.
We will let you know via email and/or a prominent notice on our Service, prior to the change becoming
effective and update the "effective date" at the top of this Privacy Policy.
You are advised to review this Privacy Policy periodically for any changes. Changes to this Privacy Policy are
effective when they are posted on this page.
Contact Us
If you have any questions about this Privacy Policy, please contact us by
email: [email protected]
Open Foris Arena is developed and hosted by the Forestry Division, FAO
81

Handbook For Open Foris Arena

Uploaded by

Copyright:

Available Formats

Handbook For Open Foris Arena

Uploaded by

Document Information

Original Title

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

Handbook For Open Foris Arena

Uploaded by

Copyright:

Available Formats

Open Foris Arena

Open Foris Team

Forestry Division, FAO

2. Typical working process 5

3. Access to Open Foris Arena 5

4. Main user interface 7

5. Selecting and creating a survey 8

6.1. Edit survey info (metadata) 11

6.2. Publish a survey 12

6.3. Delete a survey 13

6.4. Collect Import Report 14

7.1. Form Designer 17

7.1.1. About the Form Designer user-interface 17

7.1.2. Data types 19

7.1.3. Description of properties 20

7.1.4. Units of measurements 21

7.1.5. Summary on survey schema 21

7.2. Expressions and expression editor 23

8.1. Using a template file 36

8.2. Getting a new template into Arena 37

9.1. What are the data entry stages? 38

9.2. Adding and editing records 39

9.3. Deleting a record 42

9.4. Data Explorer and aggregating data 43

9.5. Export all data into CSV 47

9.5. Import data from Collect/Collect Mobile file 48

9.6. Validation report 49

10.1. Creating a processing chain 50

10.2. RStudio in programming and data processing 54

11. Users and access to Arena 58

12. Examples of expressions 62

12.1. “Relevant if” and “Apply if” rules 62

12.2. Methods and functions 64

12.3. Data validation 67

Annex 1. System architecture 69

Annex 2. Abbreviations and acronyms 70

Annex 4. Templates for forest inventory 73

Annex 5. Privacy Policy 78

What are the advantages of OF Arena over the original OF tools?

• No need for user installations;

What does OF Arena offer?

• Dynamic form designer;

2. Typical working process

● Login into the platform;

3. Access to Open Foris Arena

Arena platform is available at https://www.openforis-arena.org/

There are two methods to get access to Arena:

A. to work as a Survey Administrator.

To become a Survey Administrator, go to https://www.openforis-arena.org/

4. Main user interface

Management of survey properties, Delete a survey,

Visual view on survey hierarchy

Management of categories (i.e., code lists)

Management of taxonomic tables

Add, view, edit, delete data

Data queries, and access to data cleansing

Export all data into a Comma Separated File (CSV) file

Import Collect/Collect Mobile data

Data validation report, and access to data cleansing