Annotations are user-entered records that add structured human intelligence to robot telemetry data. These records could be defined in external systems or could be defined within Formant.  Currently, the only supported external system is Google Sheets. 

Configure or Define Annotation

Annotated data can be categorized via Google Sheets or via Formant tags. Prior to using Google Sheets, integration with Google Sheets must be enabled. 

Defining Annotation in Google Sheets

In order to annotate with data from your Google Sheet, the data must be organized in a way that Formant understands. An annotation relates a row in a spreadsheet to telemetry data. The relation requires a row identity, and that identity is the primary information required by Formant from the spreadsheet. The Sheet must be organized as follows:

• The top-left cell (A1) is a column heading and is used by Formant as the Key value (described under Advanced)
• The cells in the left column below the heading contain the values available for selection
• Additional columns (to the right) are used to constrain when the row is available

Each row in the spreadsheet defines an entity available for selection in an annotation. The first column is the key that uniquely identifies the row. Any additional columns are additional dimensions descriptive of the row. These additional dimensions are used to limit when the row is available for selection. When an annotation has multiple Sheets, selection choices are filtered to only rows that match the other selections in the sheet.

In the example below, Job Name is the column heading that is used by Formant as Key value.  Since no relationship or constrain is defined based on B1 (Location), it is not used by Formant. 

The top-left cell is usually A1, unless the Sheet is configured with a custom Range as described under Advanced.

Another example of a Google Sheet tab defined for annotation called Activity Name:

To add constrain between annotation fields, use the same header name and row options in the second column of the relationship tab. For example, see the sheets below. The Subactivity items that are part of the selected Activity Name will be displayed in the dropdown list. If Mobilization is selected as the Activity Name, then Machine at location and Equipment at location are displayed as Subactivity options and the other Subactivity items are not displayed.

Google Sheet tab named Subactivity showing the relation between Activity Name and Subactivity:

Add Annotations from Google Sheets to Formant

From the burger menu, select Settings ⇒ Annotation ⇒ Add Annotation

1. Choose a name for your annotation definition. This will be displayed on the device channels and event pages when adding new annotations. 
2. Choose devices - You can limit the devices on which a specific annotation definition applies. 
3. Add Sheets - This is the section to add sheet URLs. Each Sheet URL added is a new row within the annotation.
4. Click SAVE to save the definition and exit to the Annotation Settings page.

Adding annotation

Annotations can only be created from Device Channels or Modules

Create Annotation from Device Channel

From the device channel more menu  select Annotate

Create Annotation from Module

From the module more menu select Annotate

If Annotate is unavailable on the menu, this is because there are no Annotations defined for the current device. If more than one Annotation is available for the current device, the user is prompted with a choice of available Annotations. After the desired Annotation is selected, or if there is only one Annotation, the form for submitting annotations is displayed. The form for submitting annotations contains the following input fields:

• Start time and duration - Describe the time period being annotated. The start time is determined by the current time selected by the scrubber in the Device View. The duration is input in minutes. Duration is optional and can be updated later if it is not known when the Annotation is initially submitted.
• Drop-down select menus for each configured item in the Annotation - Each sheet in the Annotation is represented by a drop-down select menu. The options on the menu come from the Sheet as described in Google Sheet Format Specification. The options listed in each menu will be constrained by the selections made in other sheets.
• Note (optional) - Any additional notes about the annotation 
• Tagged users (optional) - Users who are linked to this specific annotation. This might not be the user who is creating the annotation.

After all form fields are filled, the annotation is submitted by selecting Save. If any required fields are not filled, the fields will be highlighted red and the annotation will not save. The user should input all of the required fields and select Save again.

Annotations are visible in Device View in the scrubber area at the bottom. Clicking an Annotation causes it to be selected and details visible in a header. The header includes an Edit button which is used to change annotated data after it has already been created. The header also includes a Delete button which deletes the annotation record.

Publish Annotation

Annotation can be published "real-time" to a Google Sheet. When an annotation is created it is appended to the sheet. When the annotation is updated, the sheet is also updated. The update is achieved by storing locally with the annotation event the spreadsheet location where the annotation was appended. It is an optional tab under Add New Annotation and designates to which sheet the annotations that use this template should be published.

There are some limitations to publishing to Google Sheets:

• The user should not add or delete any rows that have been added by Formant. This may cause the wrong rows to be updated when the annotation is updated
• Changing the annotation template will change the spreadsheet column used for each field in the template because Formant does not read the spreadsheet header row to determine what the columns are
• Only exports to the 1st tab in the spreadsheet
• Does not delete the exported annotation if it is deleted in Formant

Export Annotation

Annotations can be exported from the events page by using the Export button at the bottom of the page. The Export button respects filters on the events page. Hence, to download only the annotation, filter down the event type to Annotation and then export to Google Spreadsheet.