IGVF

A user’s guide to IGVF GoogleSheet Submitter

Spreadsheet submission tool that uses GoogleSheet’s AppScript to allow users to submit/modify metadata on the portal without installing any software or having any scripting experience. Users will need to fill in any necessary metadata in the GoogleSheet where the different object types (for example Primary Cell, Tissue, Human Donor, etc.) are populating separate tabs of the spreadsheet. For example, if you’re submitting Human Donor, Tissue, and Primary Cell, three tabs will need to be prepared. With a press of a button, the GoogleSheet will launch an embedded script that interacts with the portal and submits/modifies metadata. *If you are unfamiliar with the schema, please take a look at the Schema overview documentation.

IGVF submission (GoogleSheet’s AppScript) repository

All built-in functions can be found in the toolbar under “IGVF/ENCODE”. Image of Toolbar

Set Up

To authorize submissions, obtain access keys from your lab wrangler, if unsure you can always contact the DACC wrangling team .
Enter your access keys in the google sheet by clicking: IGVF/ENCODE -> Authorization -> Authorize for IGVF -> enter your access key pairs (i.e. ‘username’/’password’). Entering your access keys will only be required once per spreadsheet.

Authorize for IGVF in toolbar

Connect to server (set default endpoints): IGVF/ENCODE -> Settings (Global) -> Set default endpoints for READs and WRITEs. For IGVF, our sandbox site is https://api.sandbox.igvf.org/

Set defaults in toolbar

Set the schema object type (profile) you want to submit. *Note: if you are submitting multiple object types, it is mandatory to set the corresponding profile type on each of the spreadsheet tabs. IGVF/ENCODE -> Settings (This sheet) -> Set default profile name

Set profile name in toolbar

To view current endpoints and profiles: Toolbar -> IGVF/ENCODE -> Show sheet info & header legend

Submitter Spreadsheet Design and Formatting

The first two columns (‘#response’ and ‘#response_time’) provide information regarding submission responses, they are not properties of an object.

Table 1. Common response values

#Response	Description
200 or 201	Action was successful
404 or 422	Action was unsuccessful (ERROR)
409	Action was unsuccessful due to a clash (unique value conflict) between the metadata on the portal and metadata you attempted to submit. (ERROR)
401 or 403	Action was unsuccessful due to a lack of permissions/authentication (ERROR)
*Note: response can also provide other values, additional information and error messages

Each column contains a header that corresponds to a property name in schema. Header property names that are bold and <ins>underlined</ins> are searchable: Toolbar -> IGVF/ENCODE -> Search will show you all existing objects of that object type on the portal. *Note: A property value has to be selected for search.

Search in toolbar

Table 2. Object Properties Color Legend

Color	Description	Examples
<b style="color: red">Red</b>	submittable, required properties	‘taxa’ or ‘biosample_term’
<b style="color: black">Black</b>	submittable, not required but recommended if it applies to your data context	‘date_obtained’
<b style="color: blue">Blue</b>	non-submittable, an identifying property unique to the object generated by the server	‘accession’ or ‘uuid’
<b style="color: grey">Gray</b>	non-submittable, a property calculated by the system. *Note: Any values you list here for POST/PATCH will produce an error code.	‘status’ or ‘submitted_by’

Table 3. Property Value Types

Type	Requirements	Examples
Arrays	Need to have a [“ ”] wrapper; Array of objects: need to be in valid JSON format for POST/PATCH to succeed	[“A”, “B”, “C”]
Enums	A set of options (i.e. statuses)) will be available via the drop down of the cell (▼)	[Image 6]
Objects	Need to be in valid JSON format for POST/PATCH. *Note: Linked objects must already exist with identifiers in the database. If you are unsure of what identifier to use, please contact the wrangling team.	Object identifier:‘alias’,‘accession’,‘uuid’

*Note: Further details of property values can be found here.

Submission Actions

GET: Retrieve objects and properties from the portal, which can be used as a template for new submissions.

Step 1: To retrieve the available set of properties belonging to the profile (object): Toolbar -> IGVF/ENCODE -> Make new template row

Make new template in toolbar

Step 2: Enter an identifier (in aliases, accession, or uuid). *Note: multiple alias identifiers can be used for retrieving object instances

Identifiers in sheet

Step 3: To retrieve properties belonging to the profile (object type): Toolbar -> IGVF/ENCODE -> GET metadata from portal. Please wait for a couple of seconds for the script to run. You will be notified with a pop-up window when the action is complete.

Get metadata from portal in toolbar

POST: Submit new object instances (rows on the sheet) to the portal.

Step 1: Retrieve the available set of properties belonging to the profile (object): Toolbar -> IGVF/ENCODE -> Make new template row

Step 2: Fill in row values, where a row reflects a single record or instance of that object. *Note: multiple rows can be submitted at a time. Fill in values

Step 3: POST the object records: Toolbar -> IGVF/ENCODE -> POST new metadata to portal. Please wait for a couple of seconds for the script to run. You will be notified with a pop-up window when the action is complete. An assigned identifier will be generated for each new record.

PATCH: Fix properties of existing objects on the portal.

Step 1: Prepare the object sheet. Column A has to be an identifier (either accession, aliases, or uuid). The following column(s) will be the property(s) you would like to fix.

Step 2: Toolbar -> IGVF/ENCODE -> PATCH selected/all columns.

Patch options in toolbar

Review submission:

Please review the results for every record using the ‘#response’ column. See Table 1 for response values.

Troubleshooting:

If submission is unsuccessful, an error message in the ‘#response’ column will be present. Identify the row(s) and cell(s) that are producing the error(s) and fix appropriately before trying to resubmit. Please do not include already successful rows when trying to resubmit.

Table 4. Common Errors

Category	Potential solutions
Missing values	Look at object schema descriptions for all required properties
Formatting	Look for the SyntaxError: Unexpected token … is not valid JSON, again see schema descriptions for required property syntax. Example: array type property requires [“A”, “B”, “C”] formatting
Wrong value	Value is not one of the enum options (defined by the schema)

External site validation:

If the #response column is not descriptive, you can opt to use external site validation: Toolbar -> IGVF/ENCODE -> Validate

Validate in toolbar

This will compare your sheet metadata against the described profile schema by using an external JSON schema validator. Please use this function for debugging only when the error message is unclear.

*WARNING: if you are working with sensitive/restricted data, DO NOT use this feature. Instead, convert each row to JSON format and copy-paste to an internal JSON validator.