# App guidelines

> **Version 1.3
> 12.03.2021**

[ToC]

The LICCI partner data collection app is used to collect and transfer data according to the LICCI Master [Manual version 1.3](https://figshare.com/articles/Local_Indicators_of_Climate_Change_Impacts_Data_collection_protocol_/11513511/3).

---

## Introduction

The LICCI Partner/Collaborator data collection app can be found under https://licci.eu/app. Anyone can visit and use the app but in order to submit data through the app to the LICCI core team you need to obtain a user key from the licci team.

## Where to submitt the data

The folloing diagram shows which data is submitted through the app and which data is submitted through ProjectSend.

:::success
## Important notes:

Even if you work with csv files our hand-notes on the field, check the input structure of the before each Checkpoint. Also it is recommended that you put in at least one entry of each type (e.g. the site, a licci, a village, a hh survey...) as soon as you have the data. If you can submit that. The app also works on the phone and can be used offline- [see section on offline usage](https://hackmd.io/t1y1A6IhTAusfPspJi11vQ#Using-the-app-offline).

**Before you start with CP 2. You need to fill in CP1 data and submit it! Also page 2 of the site requires data input as preparation for CP2**

**Check the section on [data submission](https://licci.eu/app-guidelines/#Submission) on how to submit!**
:::

## Regular Questions:
**I cannot see my data anymore:**
Your user-key is no login. Your data is stored on the exact computer and browser you put it in. See [storage](#Storage).

## The Menu

The menu button is in the left top corner. Below the menu items you see the version of the app (e.g. v0.6.18).


### Home

The startpage contains a list of all the entries you have. It includes a search, which is [details here](#Search). Each entry is represented by a short **Preview**, which contains its title, the license and privacy (which are both predetermined and not changeable for the partner app) and some action buttons, e.g. edit, download, upload to the repo, or "add household survey". The buttons of "add ...some entry type" are not immediately visible.

### Create notes

This page allows you to create notes for all entry types. This page is described in [details here](#Notes). Notes allow you to show additional arbitrary text while creating entries.

### Settings

:::info
The settings page has a few options, some are crucial for importing and exporting your data and sending the data to the LICCI repository.
:::


#### User key

In order to submit your data you received a User key from the LICCI core team. Input it here!

#### Export data

This button dumps all entries (that you see in the My Entries page) into a single file and downloads it. [Details](#Download-importexport-amp-merging)

#### Import data

This option allows you to import the entries of a previously downloaded or exported JSON file. [Details](#Download-importexport-amp-merging)

#### Clear entries

This button removes all entries from the app. It also resets the counts for all entries, which are used for some entry types to generate the titles of their respective entries (explained [here](#Title))

:::success
It might be useful to clear your entries after the training before going to the field in order to reset the entry counts for a fresh start.
:::

## Home / Startpage

Since version 0.6.18 the startpage (Home) shows you all your entries and contains the search function.

It contains a preview of each Entry, starting with your Site entry.

## Entry types

The data collected is separated in entries. Each **entry type** has a **type description** that contains all its aspects (questions). The type description defines what data you have to put in and in which form. All the Individual parts that define any simple question or a more complex part (e.g. the input of assets) are called **aspects**. What is visible for the user are the names and descriptions of aspects and for each aspect its particular set of graphical userinterface components that allow the user to input the data in the proper format. The section [Data Input](###Data-Input) explains aspects in detail. Throughout this document in examples or otherwise we refer to aspects by their names.

For the partner app these are all entry types:

Site
Village
Local Timeline
Seasonal Calendar
Observation & LICCI
Adaptation and Coping strategy
Field type
Household survey
Individual survey

Crop Diversity System
Crop Diversity survey

There are also a few types related to the fishery protocol.

The following diagram shows the nested structure of the entries

### The Startpage

<div style="left:30%;position:relative">The LICCI domain page</div>

</br>

When you click on the banner or get to the domain page of LICCI. On top you see a list of entry types containing "Site" and "Article Review". If you click on any of these two, you create a new entry of that type. This list does not contain all the other entry types because they are nested in the context of a site (or other types nested within a site) and do not exist independently.

#### Entry type structure

Entries of the other types then "Site" and "Article Review" are nested within a site entry in the following hierarchy:

+ Site
+ Local Timeline
+ Seasonal Calendar
+ Observation & LICCI
+ Adaptation and Coping strategy
+ Crop Diversity System (optional)
+ Field type
+ Village
+ Household survey
+ Individual survey
+ Crop Diversity survey (optional)

:::success
**Explanation**
Each site contains 1 *Local Timeline* and 1 *Seasonal Calendar*. The information from SSIs and FGDs about LICCIs and LACCIs (Adaptation strategies) go into lists of *Observation & LICCI* entries and *Adaptation and Coping strategy* entries as part of your site entry.

A site must also contain at least one village. Besides the aspects defined by the protocol about village information, each village also contains a list for *household surveys*, which are the surveys conducted in this village.
The site entry also contains an aspect which allows you to opt-in to the optional crop diversity part. You are then able to create *Crop Diversity System* entries which can be selected for each village. At the end of the *Household survey* you can make up to two *Individual surveys* and also *Crop Diversity Surveys*.
:::

## Entries

First page of an entry of type Site. The header contains the type and the entrytitle, which is coming from the aspect "Site name".

### Title
Each entry has a title, which you can see on the top of the entry preview card. The title of an entry is often taken directly from an aspect of the entry. In other cases, the title is not directly setable e.g. the surveys. In these cases, the title is simply the name of the entry type + #the total number of entries of the type created: **Index-title**. This number is called **entry count**. e.g. Household survey 3

It is not crucial to remember how the titles are derived for each entry type, as it will seem intuitive and you will get used to it after a while.

**Site**: Aspect: Site name
**Local Timeline**: Aspect: Title
**Seasonal Calendar**: Index-title
**Observation & LICCI**: Aspect: LICCI (2nd page)
**Adaptation and Coping strategy**: Aspect: Adaptation measure title
**Village**: Aspect: Village name
**Crop Diversity system**: Aspect: System name
**Field type**: Aspect: Vernacular name
**Household survey**: Index-title
**Individual survey**: Index-title
**Crop Diversity survey**: Index-title

The first page of an entry contains the licence and privacy.
There are also 2 pagination buttons and some entry actions buttons.

### Pages

Entries can be divided into several pages, which logically structure the entry into sections. If that is the case, you will see navigation options in the bottom of an entry page. There will be 2 buttons to navigate back and forth (most times written as "previous page" and "next page" or sometimes with explicit name), and a select field, with which you can directly jump to a specific page, which is visible when there are many pages. Consider that in some cases, the number of pages can vary. Depending on the answer to some aspects, it is not necessary to fill out every aspect on a certain page, and in that case it is taken out of the entry.
E.g. if you answer the aspect "Same place" (The market is at the same place as the administrative center?) with yes, it will hide the page which asks about the accessibility of the closest market, since the information is already contained in the answers to the aspects which ask about the accessibility to the closest administrative center.

Entry pagination for a village shows the select field to directly jump to a certain page.

### Validation / Missing Aspects

The last page of each entry, shows a section titled "Missing aspect". This is for your support, so you do not forget to fill out anything. It does not enforce anything or does not hinder you to move on with the data collection.

Example validation section

### Navigating between entries

As explained above, most entries appear in the context of other entries and ultimately in the context of a site entry. The nested entries are part of an entrylist aspect, where each entry is represented by its title.

2 *Observation and LICCI* entries in a site.

When an entry appears in the context of another entry there are 2 ways to return to the parent entry (the entry which contains this entry).

1. Title of the parent entry on top of the page
2. Green "Save and Back" button at the bottom of a page

:::warning
Note that if you entered the entry from the domain page or the My entries the "Save and Back" button brings you back to that page.
:::

## Data input

Each entry type has a **type description** which contains details about all aspects (questions) and eventual other configurations for the usage of that type. Each aspect is of a certain type, which determines what can be filled in (e.g. text input or selecting an option). It might be useful to know all aspect types, so you know what you will encounter during the data collection.
Whatever you fill out on an aspect (your response) is simply called *value*.

Each aspect has a name, which is in bold. Below that is an optional description, wich contains information about what to fill out (if it is not obvious from the name). Sometimes, in particular with the surveys, the description contains the question for the interview and additional helpful information below in a slightly smaller font.

An aspect might have additional attributes, that define specifics (e.g. minumum for number values ...).

Since some aspects do not always need to be filled out e.g. because the answer to another aspect makes this aspect irrelevant, aspects can be conditioned. A condition means, that if another aspect has a certain value, this aspect is disabled. Disabled aspects are either still shown in grey (with additional text in the name) or completely hidden.
E.g. the village card has these 3 aspects:
- Administrative center: Name of the closest administrative center of the village.
- Same place: Is the market at the same place as the administrative center?
- Market town: Name of the closest market town, where people go to buy/sell products.

If the answer to "Same place" is yes, the aspect "Market town" will be disabled, because the answer would be the same as for the "Administrative center".

### Aspect types

There are different types of aspects, naming text and number inputs or select-inputs:

**Text** (or string) come in 2 forms. For short text (single line input field) and for long text (multiline input field).

**Number** There are 2 types for numbers: integer and floating point numbers.

**Select**: Select-aspects are aspects where you can select from a predefined list of options. They come in 2 looks. In one you see all options and can click on them right away. In the second look you see a select input box on which you can click in order to select an item.

**Multiselect:** Multiselect items are similar to select items but you are able to select multiple values. They only come in one look, with an input box, where you can check all options you want to select.

**Treeselect**: Treeselect-aspects are similar to select aspects. However the values are in a tree structure. The aspects for LICCIs and LACCIs are treeselect-aspects. There are 2 ways to select a value for a tree-select. The input-field allows you to type words, which will trigger a search that filters all options, resulting in all options that contain the query. The 2nd method is to navigate the tree through a menu. When you click the icon on the left side. What you utlimately select is a item on the lowest level of the tree (at least this is the setting for LICCIs and LACCIs).

**List**: Lists are aspects that contain a certain amount of values of the same type (**item-type**). The length of lists, might be size constrained or fixed- where the fixed length is defined by the value of another number aspect, or it is the same size of another list. Often the item-types of lists are composites. In that case you are able to open and close a list item by clicking on its title. In order to delete an item there is a button below the list-item, saying delete. In some cases you will be able to move list-items up and down, where it might be useful to change the order of items, after they have been created.

**Composite**: Sometimes an aspect doesn't come alone but only in conjunction and related to another aspect. This happens a lot with lists. For example in the "Protected areas" there is a list where the values should be the name of a protected area and the year it was declared. Thus the **item-type** of the list is a composite with the components: "Name" and "Protected area declaration year" and every time a new item is added to the list the user specifies both values for a protected area.

**Entrylist**: As explained in "Navigating between entries" section, the entries that appear in the context of other entries are contained in lists. Next to the index and the title of an subentry you see 2 icons, one to edit the entry and the second (red cross) to delete it.

:::warning
**Paginated lists**
Since both Lists and Entrylists can have many items, they will start to paginate their items if they have many items. That means, you will only see a fixed number of items, and 2 buttons to navigate through the pages of the list.
:::

:::info
**Adding entries from the preview of an entry**
For some entry types the buttons "add ...some type" are visible on the entry preview once you created one entry of that type in the context of the actual entry.
:::

### Alternative values

Sometimes aspects need to offer alternative answers of an alternative aspect-type. E.g. If you want to add a new LICCI, that is not contained in the tree, you type its name into a textfield. Also all aspects of the surveys allow you to specify that you didn't receive an answer (because the question is not applicable or the person does not want or can not answer it). In this case you will see a blue switch button before the actual input. If the switch is turned on (blue) the answer is regular, otherwise it is grey and an alternative aspect (or sometimes even a fixed answer) is shown. In some cases of aspects of type select, the switch can also be triggered by an option, which is often "Other" and the last option. This is just an alternative way to specify an alternative value.

## Survey preparation

:::warning
It is important that you complete the survey preparation before doing any survey. When you change your preparation *values* these changes will not be applied to the survey entries you already created. The reason for that is explained in Referenced values a bit below.
:::

Since some information that are collected during the SSIs and FGDs are taken to the Surveys, the second page of the Site is made in order to specify these particular values. These particular values are referenced in other parts of the data collection (within the surveys) as read-only aspects.
First it includes the randomized LICCIs and LACCIs. Both LICCIs and LACCIs are referred to by their title. Since there can be multiple observations with the same LICCI, you will see them differentiated by numbers. In addition, you will see the corresponding Observation of the LICCI that you selected. Following protocol you are supposed to randomize the LICCIs. However when multiple Observations & LICCI entries have the same LICCI you still have to select only one of them, since the questions in the survey will refer to the observation and the direction of change of a particular Observation/LICCI.

In addition, you are asked to answer some questions about knowledgeable groups and their activities. The answers are referenced during the Individual survey.

The assets with market value are also referenced in the Household survey. However they are placed on page 1 of the site.

The survey preparations for the optional Crop Diversity part are part of the villages.

### Referenced values

According to the protocol, some information of the Site information are asked about in the surveys again. E.g. the randomized LICCIs/LACCIs or the assets with market value. The application is able to manage these references for you and fetch them from one part of your data and display them at another part. The referenced values are obviously not editable at the place they are referenced from, they can only be edited at their original place. It is also important to notice, that most of the time, they are only referenced once and then stored in the entry that is referencing them. This guarantees that answers to aspects that include the references values stay valid, even if you change the references values in its original place.
An example: On the second page of the site you can specify the randomly selected LICCIs (30 for testing and 15 for the remaining surveys). In a set of test surveys you are asking about the impacts of these LICCIs on people livelihoods. When you later change the list of randomized LICCIs after the tests, reducing it to 15, the previously completed surveys will still include the original list of of LICCIs you used when you conducted the surveys.

## Entry coding

When collecting survey data with paper, individual interviews are often labeled with codes in order to identify them later on. E.g. you would have a code for each village, maybe for each district, the houses and individuals. The LICCI app keeps entries in an order of the earlier described hierarchy of entries. Site / Village / Household survey / Individual survey. However there is no one location where you see the complete code of a survey. The part of the code for an individual entry is written in its first (non editable) aspect, Village id, household id, person id. This number is identical with the index-number of that entry in the entrylist aspect (left of the entry-title) of its parent.

The default name that those (and also other entries) have contains the **entry count**, which is simply the number of all entries of that type ever created in your application and stored next to all your entries. **This number does not decrease when you delete an entry.** These numbers (for each entry type one) increase when you import entries from a file; Each number according to the number of imported entries per type. Importing and exporting is explained in the following chapter.

## Download, import/export & merging

### Download or export

Downloading your data can be used to backup your data or allow you to transfer it to another device or to share it with a colleague in order to work in parallel. There are two ways to download your data and in general for the partners they result in an equal file. When you download your data on the progressive webapp it will be exactly the same as downloading a file in your web browser. By default it will download a file with the file extension .json into your Downloads folder. JSON files can be read and edited by any text-editor.
The first way to download your data is by clicking the download button at the bottom of your Site entry.
It is also included in the preview of the site (probably the first entry-preview that you see on the LICCI domain page or the My Entries page). The download JSON file will not only contain the Site entry but also all its child-entries that are contained in all its entrylist-Aspects, recursively. Basically the whole LICCI partner data.

The second way is to use the Export button on the Settings page. It will download all your entries. If you only have one site (with its nested entries) it is identical with downloading that site, because all nested entries will be downloaded when you download that site.

### Import

In order to import the entries from an JSON file, you can use the Import button on the settings page. It allows you to select a file from your computer. It is important to notice that the import will perform a merge of entries, if the entries that are contained in that file already exist in your entries.

### Merging

:::warning
**Merging files has been deactivated in version 0.6.18**
:::

## Submission
:::info
In order to submit your data to the LICCI core team you must use the submission method of the LICCI app.
:::

In order to be able to submit your data you need to specify your **User key** that you received from the LICCI core team, on the settings page. Now you can press the "upload to the repo" button, which you find either with the site entry preview or at the bottom of the site entry.

You do not need to care about duplicate submissions. In general we consider your most recent submission as valid. You can rather consider it as an easy way to backup your data, when you are connected to the internet.

## Notes

The notes section allows you to add notes to aspects of the entry types. These notes can be arbitrary text that you want to have shown, when you create entries. It can for example include a translation of a survey question. The structure of note creation pages is the same as when you create an entry. However, for all aspects you only see its title and description, but not the input component. Instead you have the possibility to create or edit a note for each aspect and its parts. The note pages seem to show more aspects then when you create an entry.
For example, on the site, the aspect "Protected areas" is a list and each list item contains the aspects: "Name", "Protected area declaration year". The notes page contains:

- Protected areas
- Protected area
- Name
- Protected area declaration year

It shows "Protected area", which is not visible when creating an entry. That is because for lists, where the **item-type** is a composite, the name and its description are not shown when creating them. They are generally not useful to show, as the description of the list explains what the aspect and its components are about,

The notes are shown in the entries as blue text below the description of an aspect. You can also save and load (import/export) your notes, if you want to share them. Looking at the structure of the exported file (in JSON format). If you have taken some notes somewhere else, you can also edit the json file in any text editor and load the result back into the app.

## Search

The overview of entries contains a search section in order to quickly navigate to a specific entry. The search contains a text input field a entry type filter and the search results. The search query will be automatically triggered once there are 4 characters in the text input field or when you press the search icon on the right. The entry type filter allows you to show only entries of a certain type. As a result you see the previews of entries matching your query from the text input field and only those one specified entry type (if the type filter is used).

The search compares your with all titles of all your entries. In addition it also compares it with certain aspects of different entry types. The configuration in which aspects will be searched is preset around a simple rational that allows you to get an overview about the LICCI, Adaptation and Coping strategies and their relationships. A future version will allow the user to specify the configuration for the aspect search or allow them to specify the aspect on the spot.

For now the search for a text in aspects are:

__Observation and LICCI:__
- Observation
- LICCI
- Other LICCIs
- Drivers

__Adaptation and Coping strategy:__
- Adaptation measure
- Local observation
- Adaptation, Coping category
- Other LACCIS

## Storage

The entries are constantly stored in a database in your browser. Whenever you leave an entrypage this storage is updated.
This is how your browser keeps your entries when you close your browser and later open the page again.
This includes
- Your entries
- Your User key
- The type notes
- The entry counts

This also means they might be cleared when you perform such an activity on your browser settings; e.g. clear browser data. The storage also works when you added the app to the home screen of your mobile device. The app still uses the same storage.

The entries and type notes can be backed up and shared and the entry count will be updated when you load a file. (As explained in merging)

## Updates

However updating an entry, might still require exchange with the core team (with Ramin). In the case that an updated type description would change some aspect description significantly data can be lost when you update. That is why we will try to keep the updates of entrytypes to an minmimum and notify you if you your data need some restauration.

## Resulting csv tables

The resulting data in JSON format can be converted into cvs tables (at the moment not automatically but done by Ramin). The results are multiple csv tables, one for each entry type. An entry is represented by (at least) one row. Since entries can contain lists of aspects, the chosen (at the moment only) representation, puts lists-values in extra rows. An entry can always be identified by the value in the first row: `ID`.

## Using the app offline

When you want to use the licci app offline so that you can input data while being in a remote place you can "install it" from the website directly (https://licci.eu/app). This type of installable websites is called progressive web apps (PWA). Even tho it seems to be installed on your device and looks like a normal (native) application, it stills runs in the browser when you use it. That is why, it makes a difference with which browser you download it. At the moment we advice you to use the **Google Chrome browser**! Consider that PWA are for mobile devices only. When you some options in browsers on desktop devices suggesting that you can "install" or "download" the page, feel free to try that out and see if it works being offline. If it does work - let me know :).

### How to install the LICCI PWA with Chrome

When you visit the LICCI app page and do not have it installed, the latest version of Chrome will show up a popup at the bottom of the screen suggesting you to "Add LICCI to Home screen", which is a synonym expression for installing the PWA. If you click on that it asks you again to add it.
:::warning
Make sure that you loaded the latest version of the app - we would keep you up to date about version updates. At the moment (24.01.2020) we are at version 0.6.17, however an update is prpbaly coming within the next 2 weeks (0.6.17a).
:::
You should after a short moment see the LICCI Icon, maybe with the small chrome icon attached, either directly on your home screen (on one of its pages) or in your applications: from the home screen swipe up from the middle bottom to see all your installed applications. You can also reach the installation menu, by click on the browser menu (three vertical dots on the right top) -> "Add to home screen" -> Add (-> Add).

Start the application, while still being connected either from your home screen or from the application menu.
:::info
Similar to the desktop on a convention computer, apps on the home screen are shortcuts to the installed application. You can add (longpress on the icon in the apps menu -> "Add to home"), remove (longpress on the icon on the home screen-> "Remove from home") or move apps around your home screen (longpress and move).
:::

<style>
/* Three image containers (use 25% for four, and 50% for two, etc) */
.column {
float: left;
width: 49%;
padding: 5px;
}

/* Clear floats after image containers */
.row::after {
content: "";
clear: both;
display: table;
}
</style>

<div class="row">
<div class="column">
<img src="https://licci.eu/app-guidelines/imgs/app-apps.jpeg"/>
<div>
the app in the applications menu
</div>
</div>
<div class="column">
<img src="https://licci.eu/app-guidelines/imgs/app-home.jpeg"/>
<div>
the app on the home screen
</div>
</div>
</div>

### Updating the installed PWA

Since the behaviour trying to update the app is always a bit unpredictable I will explain the easy method and the cumbersome method (not really but its annyoing that it seems to work only like that sometimes), that seems to be the only alternative, when the app does not update that way.

**Easy method:**
- close the app
- press the left button (3 vertical lines) on the navigation menu in the bottom of the device. all open apps are shown.
- press on the LICCI app window and swipe it up, out of the screen

All open apps

- Connect to the internet
- Open the app again. The app is nice and fetches the latest version. That's it.

**Easy method 2 (only available from version 0.6.17a):**

- close the app
- open the app
- press the "update application" button

**Cumbersome method:**
Even tho you can see the latest version in the browser, the app doesn't seem to update- **even when you uninstall and install it again**. What you have to do is to uninstall it, clear the browser cache and install it again.

1. Uninstall the app:
You can uninstall like that by: longpress on the app icon (either in the app menu or home screen)- a menu shows up; click "Uninstall".

2. Clear the browser cache:
longpress on the Chrome app- a menu shows up; click "App info". On the app info page, click on "Storage". On the storage page click on the button on the upper right: "Clear cache". That's it. You can go back to your home screen and/or close the info page.

<div class="row">
<div class="column">
<img src="https://licci.eu/app-guidelines/imgs/chrome-settings.jpeg"/>
<div>
Chrome App info
</div>
</div>
<div class="column">
<img src="https://licci.eu/app-guidelines/imgs/chrome-storage-settings.jpeg"/>
<div>
Chrome Storage info
</div>
</div>
</div>

<br/>

3. Install the app again.

<br/>

:::success
We suggest you to backup your data regularly. However, updating the app (even the cumbersome way) should not remove your entries.
:::