> For the complete documentation index, see [llms.txt](https://documentation.dnanexus.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://documentation.dnanexus.com/admin/trusted-research-environments/preparing-resource-inventory-for-file-only-tre.md). # Prepare a Resource Inventory for a File-Only TRE Prepare the File Inventory and Data Collections assets for a file-only Trusted Research Environment. {% hint style="info" %} Apollo and Trusted Research Environments licenses are required to use Trusted Research Environments on the DNAnexus Platform. [Contact DNAnexus Sales](mailto:sales@dnanexus.com) for more information. {% endhint %} A file-only Trusted Research Environment (TRE) uses a File Inventory TSV and a Data Collections JSON file (along with an optional Participant IDs (PID) CSV file) to define which files researchers can request and how the platform dispenses them. Prepare and upload these assets before you configure the TRE Resource Inventory. The assets have different access requirements. Authorized TRE users can access the Data Collections JSON before an access request is approved. The File Inventory TSV, any optional Participant IDs CSV, and all bulk source files must remain private. Researchers receive only the filtered, dispensed files after their request is approved. {% hint style="warning" %} Do not store the File Inventory TSV, Participant IDs CSV, 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. {% endhint %} ## 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, optional Participant IDs CSV, and the bulk source files they reference | TRE system and TRE admins 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 | Source identifier for the participant associated with the file. The column header must be `eid`. Values must be alphanumeric when validated against a Participant IDs CSV. Duplicate `eid` values across rows are allowed when a participant has multiple files. Leave blank for population-level or shared files. | | `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`, `rename`, `remap_fam`, `remap_sample`, or `remap_rel` (or `watermark_vcf` when configured with DNAnexus Professional Services). | ### Choose a Dispensal Mode The `dispensal` column controls how the platform names, transforms, 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` (or the mapped pseudonymized EID when [pseudonymization](/admin/trusted-research-environments/pseudonymization.md) is enabled), `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. * `remap_fam`, `remap_sample`, and `remap_rel` rewrite participant identifiers inside PLINK `.fam`, Oxford `.sample`, and `.rel` relationship array files using the project's EID mapping. Participant identifiers not present in the mapping are redacted in `.fam` and `.sample` files and omitted from `.rel` files. Multi-sample pVCF header watermarking (`watermark_vcf`) is also supported through a platform-managed watermarking workflow. Contact [DNAnexus Professional Services](https://www.dnanexus.com/professional-services) to configure pVCF watermarking for your inventory. The following example contains two participant files and one shared reference file: ```tsv eid field_id field_id_to_use_for_filename resource_id instance_id array_id file_id version folder_prefix name_or_suffix dispensal PARTICIPANT00123 1 1 file-ExampleFileId001 /Bulk/Whole genome sequences/VCFs/ .g.vcf.gz rename PARTICIPANT00124 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](/developer/api.md) and formatting the results into these columns. ## Prepare the Participant IDs (PID) CSV (Optional) On a file-only TRE where neither a Data Showcase nor a Tabular Data Inventory is enabled, the platform derives the participant list from the `eid` column of the File Inventory TSV by default. You can optionally provide a standalone Participant IDs (PID) CSV file to override automatic derivation when your study cohort includes participants who do not have individual rows in the File Inventory TSV. For example, participants represented only in shared array files. When you supply a Participant IDs CSV, the file must meet the following requirements: * **Location** — The file must reside in the same project as the File Inventory TSV (`pids.project` must match `file.project`). * **File state** — The file must be in the `closed` state before you link it to the inventory. * **Header** — The header row must contain `PID`. * **Values** — Each subsequent row must contain one unique, alphanumeric participant identifier. * **Coverage** — Every non-empty `eid` value referenced in the File Inventory TSV must be alphanumeric and must appear in the Participant IDs CSV. Valid Participant IDs CSV example: ```csv PID PARTICIPANT00123 PARTICIPANT00124 PARTICIPANT00125 ``` ## 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. ```json [ { "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: ```shell dx select "Project With TRE Resources" dx describe --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](/admin/trusted-research-environments/creating-a-tre.md) or [update an existing Resource Inventory](/admin/trusted-research-environments/managing-tre-lifecycle.md#update-the-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, optional Participant IDs CSV, 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. When participant pseudonymization is enabled, the platform also provisions a dedicated TRE watermark project managed alongside the working project. Organization administrators for the TRE billing organization can add themselves when troubleshooting is required. {% hint style="warning" %} Do not add inventory assets to the working project or watermark project, and do not modify or delete their contents or permissions. Manual changes can disrupt dispensal and support workflows. {% endhint %} The working organization contains the TRE admins and the TRE robot user. It supports internal TRE operations, including file download policy management and, when pseudonymization is enabled, watermarking authority. The exact organization name and ID depend on the TRE. {% hint style="warning" %} Do not modify the working organization directly. Use the supported TRE controls to manage TRE admins and related access. {% endhint %} --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://documentation.dnanexus.com/admin/trusted-research-environments/preparing-resource-inventory-for-file-only-tre.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.