Prepare a Resource Inventory for a File-Only TRE

Prepare the File Inventory and Data Collections assets for a file-only Trusted Research Environment.

Apollo and Trusted Research Environments licenses are required to use Trusted Research Environments on the DNAnexus Platform. Contact DNAnexus Sales for more information.

A file-only Trusted Research Environment (TRE) uses a File Inventory TSV and a Data Collections JSON file to define which files researchers can request and how the platform dispenses them. Prepare and upload both assets before you configure the TRE Resource Inventory.

The two assets have different access requirements. Authorized TRE users can access the Data Collections JSON before an access request is approved. The File Inventory TSV and all bulk source files must remain private. Researchers receive only the filtered, dispensed files after their request is approved.

Do not store the File Inventory TSV or bulk source files in the project that is shared with authorized TRE users. Treat all content in that shared project as visible to those users.

Organize Inventory Assets into Projects

Place inventory assets in projects according to their access requirements. All projects must be in the same region as the TRE and billed to the TRE organization.

Project	Contains	Accessible by
Collections project	Data Collections JSON	Authorized users, TRE admins, and reviewers as soon as they are added to the TRE
Inventory data project	File Inventory TSV and the bulk source files it references	TRE system only, never directly by researchers

Use short, descriptive project names that include the TRE name and the project's purpose. For example, use Collections - Genomics Research and Data Inventory - Genomics Research. Use the project summary or description to record the data version and other context.

Prepare the File Inventory TSV

The File Inventory is a tab-separated values file in which each row represents a file that can be dispensed. The field_id value connects each row to one or more fields in the Data Collections JSON.

Column	Required	Description
eid	No	Identifier for the participant associated with the file. Accepts any string. Leave blank for population-level or shared files. This column can also be named pid, depending on your data model.
field_id	Yes	Data type category identifier. Give each distinct data type a unique value.
field_id_to_use_for_filename	No	Overrides field_id when generating the dispensed filename. Use this when paired file types must share a filename prefix.
resource_id	No	Optional tag applied during dispensal for descriptive routing.
instance_id	No	Optional tag for the specific instance of data collected.
array_id	No	Optional tag for the array index.
file_id	Yes	DNAnexus file object ID, such as file-xxxx. The file must be in a project in the TRE region.
version	No	Integer version number for the file.
folder_prefix	Yes	Directory path where the file is placed in the researcher's project. The value must begin with /.
name_or_suffix	No	For rename dispensal, the file extension or final filename. For as-is dispensal, leave blank to preserve the original filename or provide a replacement filename.
dispensal	Yes	How the platform handles the file. Must be as-is or rename.

Choose a Dispensal Mode

The dispensal column controls how the platform names and delivers each file:

• as-is places the file at folder_prefix. If name_or_suffix is blank, the original filename is preserved. If it has a value, that value becomes the filename. Use this mode for population-level files, shared reference files, or files without a participant-specific name.

• rename constructs a participant-specific filename using eid, field_id, and optional instance_id and array_id, followed by name_or_suffix. The original filename is replaced. Use this mode for individual participant files.

The following example contains two participant files and one shared reference file:

eid	field_id	field_id_to_use_for_filename	resource_id	instance_id	array_id	file_id	version	folder_prefix	name_or_suffix	dispensal
P-00123	1	1				file-ExampleFileId001		/Bulk/Whole genome sequences/VCFs/	.g.vcf.gz	rename
P-00124	1	1				file-ExampleFileId002		/Bulk/Whole genome sequences/VCFs/	.g.vcf.gz	rename
	7	7				file-ExampleFileId004		/Bulk/Shared references/	GRCh38_reference.fa	as-is

For large datasets, generate the File Inventory programmatically by querying the source project through the DNAnexus Platform API and formatting the results into these columns.

Prepare the Data Collections JSON

The Data Collections JSON defines the groups of data that researchers can select when creating an access request. Each collection has a name, description, mandatory setting, file count, fields, and a link to supplementary documentation.

The fields array connects the JSON to the File Inventory. For each field object, set id to a field_id value from the TSV. When a researcher requests a collection and the request is approved, the platform dispenses the File Inventory rows whose field_id matches a field in that collection.

Property	Type	Required	Description
name	string	Yes	Display name of the collection.
description	string	Yes	Description shown in the access request UI.
mandatory	boolean	Yes	Whether the collection is included in every approved request and cannot be deselected.
files	integer	Yes	Number of files in the collection. Count the File Inventory rows for the collection's field IDs.
fields	array of objects	Yes	File Inventory fields in this collection. Each object has an id and downloadRestricted property.
detailsURL	string	Yes	URL of supplementary documentation about the collection.

Configure Per-Field Download Restrictions

Each object in fields must include the following properties:

Property	Type	Required	Description
id	string	Yes	A field_id value from the File Inventory TSV.
downloadRestricted	boolean	Yes	Whether files for this field can be downloaded from a dispensed project.

When downloadRestricted is true, the platform blocks downloads for that field even if the project-level Download Access policy allows downloads. When it is false, the field follows the project's Download Access policy.

[
  {
    "name": "Whole Genome Sequencing Data",
    "description": "Germline variant call files for consented participants.",
    "mandatory": false,
    "files": 5000,
    "fields": [
      {
        "id": "1",
        "downloadRestricted": true
      }
    ],
    "detailsURL": "https://example.com/wgs-data-guide"
  },
  {
    "name": "Whole Exome Sequencing Data",
    "description": "Exome variant call files for consented participants.",
    "mandatory": false,
    "files": 4800,
    "fields": [
      {
        "id": "2",
        "downloadRestricted": false
      }
    ],
    "detailsURL": "https://example.com/wes-data-guide"
  }
]

The WGS files in this example cannot be downloaded, regardless of the project-level policy. The WES files follow the project-level policy.

Download Access policy	Per field downloadRestricted policy	Result
Enforce on	true or false	Downloads are blocked.
Enforce off	true	Downloads are blocked.
Enforce off	false	Downloads are allowed.
Defer to project settings	true	Downloads are blocked.
Defer to project settings	false	The project setting determines whether downloads are allowed.

Get Resource Identifiers

When you configure the Resource Inventory, enter each inventory resource as a fully qualified identifier in the form project-xxxx:object-xxxx. Use the following command to get the identifier for a file or record:

dx select "Project With TRE Resources"
dx describe <name-or-id> --json | jq -r '"\(.project):\(.id)"'

You can also select the resource from the UI dropdown when you configure the Resource Inventory.

Configure the TRE

After you prepare and upload the assets, create and publish the TRE or update an existing Resource Inventory.

TRE Working Resources

DNAnexus provisions and manages working resources for internal TRE operations. These resources are separate from the inventory projects that contain the File Inventory TSV, Data Collections JSON, and bulk source files. You do not create or populate the working resources as part of preparing the Resource Inventory.

The platform creates a TRE working project and TRE robot user for internal dispensal operations. Only the TRE robot user has direct access to the working project.

Organization administrators for the TRE billing organization can add themselves when troubleshooting is required.

Do not add inventory assets to the working project or modify its contents or permissions. Manual changes can disrupt dispensal and support workflows.

The working organization contains the TRE admins and the TRE robot user. It supports internal TRE operations, including file download policy management. The exact organization name and ID depend on the TRE.

Do not modify the working organization directly. Use the supported TRE controls to manage TRE admins and related access.