APGAP Platform Administrator Guide#

This guide covers all administrative operations available to Platform Admins, including routine configuration tasks, user and lab management, metadata template management, and recovery procedures for infrastructure failures.

Platform Admins have unrestricted access across all organizations, labs, projects, and users. Handle this access with care — most destructive operations (deleting organizations, bulk-promoting files) cannot be reversed through the UI.

1. Platform Admin access and constraints#

Platform Admin status is controlled by the is_platform_admin boolean flag on a user’s account. When this flag is set, the user is automatically added to the Platform Admin Django permission group, which governs all API-level access checks.

Important constraints for Platform Admin accounts:

  • Platform Admins cannot be added to individual Labs or Projects. The system enforces this — if a user needs both admin access and lab membership, use the Data Analyst role instead (platform-wide analytics access, no lab membership restrictions).
  • Platform Admin and Data Analyst flags are mutually exclusive in practice — a user should have one or the other, not both.
  • Changes to the is_platform_admin flag take effect immediately. The user does not need to log out and back in.

To set or remove Platform Admin status for a user, navigate to Admin → User Management, find the user, click the edit icon, and toggle the Platform Admin switch.

2. Initial platform setup#

For a new APGAP deployment, complete these steps in order. Skipping steps or doing them out of order will cause errors (for example, you cannot create a lab without first having an organization).

  1. Add approved email domains to the domain whitelist
  2. Create at least one Organization
  3. Create user accounts (domain must be whitelisted first)
  4. Create Labs within their Organizations (triggers GCP provisioning)
  5. Assign users to Labs
  6. Configure metadata templates for each Source Type

Each step is covered in detail in the sections below.

3. Managing the domain whitelist#

The domain whitelist controls which email domains are permitted to have accounts in APGAP. A user cannot be created unless their email domain is on the whitelist.

Important: Removing a domain from the whitelist does not deactivate existing users from that domain. Existing accounts remain active and can still log in. The whitelist is only checked when creating new accounts.

Add a domain#

Navigate to Admin → Domain Whitelist

  1. Click New Domain (or Add Domain depending on your version)
  2. Enter the domain — include the extension (e.g., asu.edu, tgen.org, nau.edu)
  3. Optionally add a description to note the associated organization
  4. ClickAdd Domain

Edit a domain#

  1. Navigate to Admin → Domain Whitelist
  2. Find the domain and click the Edit icon (pencil)
  3. Make your changes
  4. Click the checkmark to save, or the X to cancel

Delete a domain#

  1. Navigate to Admin → Domain Whitelist
  2. Find the domain and click the Delete icon (trash can)
  3. Confirm the deletion

4. Managing organizations#

Organizations are the top-level container in APGAP. Each institution — ASU, ADHS, University of Arizona, NAU, TGen, or a partner agency — should be one Organization. Labs belong to Organizations.

Create an organization#

  1. Navigate to Admin → Organizations
  2. Click Add New Organization
  3. Enter the Organization Name (must be unique across the platform)
  4. Set Default Approve Analytical Dataset Requests if applicable:
  • When enabled, access requests for files from this organization’s labs are automatically approved when requested by users within the same organization
  • Use this for internal teams or highly trusted partners where per-request approval is not required
  1. Click Add Organization

Delete an organization#

⚠️ Deleting an organization is not reversible through the UI. All associated labs and data will remain in the database but the organization will be hidden from all views.

  1. Navigate to Admin → Organizations
  2. Find the organization and click the Delete icon
  3. In the confirmation dialog, click Yes, delete

Organizations are soft-deleted (active = False) — the underlying data is preserved but the organization is invisible to users.

5. Managing labs#

Labs belong to Organizations. Creating a lab triggers a Cloud Build pipeline that provisions a dedicated Google Cloud project for the lab — including a GCS bucket, IAM configuration, and VPC. This process takes 5 to 15 minutes.

Every lab must have at least one Lab Director before users can be assigned or files can be uploaded.

Create a lab#

Before proceeding: Ensure the Organization exists and the designated Lab Director’s user account has been created.

  1. Navigate to Labs
  2. Click Create Lab
  3. In the dialog:
    • Select the Organization
    • Enter the Lab Name (display name)
    • Add at least one Lab Director
  4. Click Create Lab

The lab will appear in the roster with Build Status: WORKING while infrastructure is being provisioned. When complete, the status changes to SUCCESS and the lab can accept file uploads.

Do not add users or attempt file uploads until the Build Status shows SUCCESS.

Monitor lab provisioning#

To check provisioning status:

  1. In the Labs list, look at the Build Status column for the lab
  2. If you need more detail, check Cloud Build logs in the GCP Console:
  • GCP Console → Cloud Build → History
  • Filter by trigger: lab-tf-apply
  • Find the run associated with your lab’s project_prefix

Edit a lab#

Lab names and descriptions can be edited through the UI:

  1. Click Labs → select the lab
  2. Click Edit
  3. Update the description or other editable fields
  4. Click Save

The lab’s project_prefix (used for GCP resource naming) cannot be changed after creation.

6. Managing users#

APGAP does not support self-signup. All user accounts must be created by a Platform Admin.

Create a user#

Before proceeding: Ensure the user’s email domain is on the domain whitelist.

  1. Navigate to Admin → User Management
  2. Click Add User
  3. Fill in:
    • Email address — must match the Google account they’ll use to log in
    • Name — display name in the platform
    • Organization — the organization this user belongs to
  4. Set role flags if applicable:
    • Platform Admin — grants full platform access; user cannot be added to labs
    • Data Analyst — grants platform-wide analytics access; user cannot be added to labs
  5. Click Add User

The user will receive a welcome notification. They log in by navigating to the APGAP URL and clicking Sign in with Google using the email address you registered.

If you see “Domain not authorised” when creating a user, the email domain has not been added to the whitelist yet — add it first (see Section 3).

Edit a user#

  1. Navigate to Admin → User Management
  2. Find the user and click the Edit icon
  3. Select Edit User Details
  4. Make your changes and click Save

Changing a user’s email address is possible but requires that the new address matches an active Google account. The user will need to use the new email to log in after the change.

Deactivate or delete a user#

User deactivation is handled through the Django admin panel (/admin/). In the main platform UI, you can remove a user from all their labs, which effectively revokes their access to lab data, but their account remains active. For full deactivation, use the Django admin panel:

  • /admin/users/user/ → find the user → uncheck Active → save

7. Managing lab membership#

Assign a user to a lab#

Users can be assigned to labs from two places: through Admin → User Management or directly from the Lab Roster tab within a lab. The Lab Roster approach is generally more convenient.

From the Lab Roster:

  1. Navigate to the lab → Lab Roster tab
  2. Click Assign User
  3. Search for the user by email
  4. Select their Role:
    • Lab Director — full lab admin, can approve access requests and manage roster
    • Lab Collaborator — read/write, no admin capabilities
    • Lab Reader — read-only
    • Bioinformatics User — assign at the project level, not the lab level
  5. Click Assign User

From User Management:

  1. Navigate to Admin → User Management
  2. Find the user → click Assign Lab
  3. Toggle the Lab Director switch if applicable
  4. Select the lab from the dropdown
  5. Click Assign

Assign a user to a project#

After assigning a user to a lab, they can be assigned to specific projects within that lab:

  1. Navigate to the lab → Projects tab → select the project
  2. Click the Users tab → Assign User
  3. Select the user and their project permissions
  4. Click Assign User

Remove a user from a lab#

  1. Navigate to the lab → Lab Roster tab
  2. Find the user and click the trash can icon
  3. Click Yes, Remove to confirm

8. Managing metadata templates#

Metadata templates define which fields appear for each Source Type (Human, Wastewater, Wildlife, Animal/Livestock, etc.) and which are required for a file to reach PRIMARY status. Template changes affect all labs and all future CSV template downloads.

This is an infrequently needed operation — only make changes when adding support for a new Source Type or when a field definition needs to change. Incorrect changes can cause bulk metadata import failures across all labs.

View and edit a metadata template#

  1. Navigate to Admin → Metadata Management
  2. Select the Source Type to configure
  3. You’ll see the current fields with their key name, required status, value type, and sort order

To edit an existing field:

  1. Click the Edit icon next to the field
  2. Update the settings:
    • Is Required — whether the field must be filled for PRIMARY status
    • Value Type — TEXT, NUMBER, DATE, or SELECT
    • Multiple values — whether a field can accept more than one value (SELECT type only)
    • Sort Order — display position in the CSV template and UI
  3. For SELECT type fields, add or remove allowable values using the +Value button
  4. Click Save To remove a value from a SELECT field, click the X next to the value. Note that some core fields cannot be deleted — these are protected because they are required for NCBI/standards compatibility.

Add a custom metadata key#

  1. Navigate to Admin → Metadata Management
  2. Click Add Custom Key/Value
  3. In the dialog:
    • Enter the Key Name — will be normalized to uppercase automatically
    • Select the Key Format (TEXT, NUMBER, DATE, or SELECT)
  4. Click Add Key The new key will appear in the Metadata Management view and can be added to Source Type templates. It will also appear in CSV template downloads for any Source Type it is associated with.

Delete a custom key#

Built-in keys (required for standards compliance) cannot be deleted. Custom keys can be deleted from the Metadata Management view:

  1. Navigate to the key you want to delete
  2. Click the Delete icon
  3. A confirmation dialog will appear — click Yes to confirm ⚠️ Deleting a key also removes all associated metadata values from any files that have that key. This is irreversible.
Backward APGAP Quickstart Guide APGAP How-To Guide Forward