DNAnexus Documentation
APIDownloadsIndex of dx CommandsLegal
  • Overview
  • Getting Started
    • DNAnexus Essentials
    • Key Concepts
      • Projects
      • Organizations
      • Apps and Workflows
    • User Interface Quickstart
    • Command Line Quickstart
    • Developer Quickstart
    • Developer Tutorials
      • Bash
        • Bash Helpers
        • Distributed by Chr (sh)
        • Distributed by Region (sh)
        • SAMtools count
        • TensorBoard Example Web App
        • Git Dependency
        • Mkfifo and dx cat
        • Parallel by Region (sh)
        • Parallel xargs by Chr
        • Precompiled Binary
        • R Shiny Example Web App
      • Python
        • Dash Example Web App
        • Distributed by Region (py)
        • Parallel by Chr (py)
        • Parallel by Region (py)
        • Pysam
      • Web App(let) Tutorials
        • Dash Example Web App
        • TensorBoard Example Web App
      • Concurrent Computing Tutorials
        • Distributed
          • Distributed by Region (sh)
          • Distributed by Chr (sh)
          • Distributed by Region (py)
        • Parallel
          • Parallel by Chr (py)
          • Parallel by Region (py)
          • Parallel by Region (sh)
          • Parallel xargs by Chr
  • User
    • Login and Logout
    • Projects
      • Project Navigation
      • Path Resolution
    • Running Apps and Workflows
      • Running Apps and Applets
      • Running Workflows
      • Running Nextflow Pipelines
      • Running Batch Jobs
      • Monitoring Executions
      • Job Notifications
      • Job Lifecycle
      • Executions and Time Limits
      • Executions and Cost and Spending Limits
      • Smart Reuse (Job Reuse)
      • Apps and Workflows Glossary
      • Tools List
    • Cohort Browser
      • Chart Types
        • Row Chart
        • Histogram
        • Box Plot
        • List View
        • Grouped Box Plot
        • Stacked Row Chart
        • Scatter Plot
        • Kaplan-Meier Survival Curve
      • Locus Details Page
    • Using DXJupyterLab
      • DXJupyterLab Quickstart
      • Running DXJupyterLab
        • FreeSurfer in DXJupyterLab
      • Spark Cluster-Enabled DXJupyterLab
        • Exploring and Querying Datasets
      • Stata in DXJupyterLab
      • Running Older Versions of DXJupyterLab
      • DXJupyterLab Reference
    • Using Spark
      • Apollo Apps
      • Connect to Thrift
      • Example Applications
        • CSV Loader
        • SQL Runner
        • VCF Loader
      • VCF Preprocessing
    • Environment Variables
    • Objects
      • Describing Data Objects
      • Searching Data Objects
      • Visualizing Data
      • Filtering Objects and Jobs
      • Archiving Files
      • Relational Database Clusters
      • Symlinks
      • Uploading and Downloading Files
        • Small File Sets
          • dx upload
          • dx download
        • Batch
          • Upload Agent
          • Download Agent
    • Platform IDs
    • Organization Member Guide
    • Index of dx commands
  • Developer
    • Developing Portable Pipelines
      • dxCompiler
    • Cloud Workstation
    • Apps
      • Introduction to Building Apps
      • App Build Process
      • Advanced Applet Tutorial
      • Bash Apps
      • Python Apps
      • Spark Apps
        • Table Exporter
        • DX Spark Submit Utility
      • HTTPS Apps
        • Isolated Browsing for HTTPS Apps
      • Transitioning from Applets to Apps
      • Third Party and Community Apps
        • Community App Guidelines
        • Third Party App Style Guide
        • Third Party App Publishing Checklist
      • App Metadata
      • App Permissions
      • App Execution Environment
        • Connecting to Jobs
      • Dependency Management
        • Asset Build Process
        • Docker Images
        • Python package installation in Ubuntu 24.04 AEE
      • Job Identity Tokens for Access to Clouds and Third-Party Services
      • Enabling Web Application Users to Log In with DNAnexus Credentials
      • Types of Errors
    • Workflows
      • Importing Workflows
      • Introduction to Building Workflows
      • Building and Running Workflows
      • Workflow Build Process
      • Versioning and Publishing Global Workflows
      • Workflow Metadata
    • Ingesting Data
      • Molecular Expression Assay Loader
        • Common Errors
        • Example Usage
        • Example Input
      • Data Model Loader
        • Data Ingestion Key Steps
        • Ingestion Data Types
        • Data Files Used by the Data Model Loader
        • Troubleshooting
      • Dataset Extender
        • Using Dataset Extender
    • Dataset Management
      • Rebase Cohorts and Dashboards
      • Assay Dataset Merger
      • Clinical Dataset Merger
    • Apollo Datasets
      • Dataset Versions
      • Cohorts
    • Creating Custom Viewers
    • Client Libraries
      • Support for Python 3
    • Walkthroughs
      • Creating a Mixed Phenotypic Assay Dataset
      • Guide for Ingesting a Simple Four Table Dataset
    • DNAnexus API
      • Entity IDs
      • Protocols
      • Authentication
      • Regions
      • Nonces
      • Users
      • Organizations
      • OIDC Clients
      • Data Containers
        • Folders and Deletion
        • Cloning
        • Project API Methods
        • Project Permissions and Sharing
      • Data Object Lifecycle
        • Types
        • Object Details
        • Visibility
      • Data Object Metadata
        • Name
        • Properties
        • Tags
      • Data Object Classes
        • Records
        • Files
        • Databases
        • Drives
        • DBClusters
      • Running Analyses
        • I/O and Run Specifications
        • Instance Types
        • Job Input and Output
        • Applets and Entry Points
        • Apps
        • Workflows and Analyses
        • Global Workflows
        • Containers for Execution
      • Search
      • System Methods
      • Directory of API Methods
      • DNAnexus Service Limits
  • Administrator
    • Billing
    • Org Management
    • Single Sign-On
    • Audit Trail
    • Integrating with External Services
    • Portal Setup
    • GxP
      • Controlled Tool Access (allowed executables)
  • Science Corner
    • Scientific Guides
      • Somatic Small Variant and CNV Discovery Workflow Walkthrough
      • SAIGE GWAS Walkthrough
      • LocusZoom DNAnexus App
      • Human Reference Genomes
    • Using Hail to Analyze Genomic Data
    • Open-Source Tools by DNAnexus Scientists
    • Using IGV Locally with DNAnexus
  • Downloads
  • FAQs
    • EOL Documentation
      • Python 3 Support and Python 2 End of Life (EOL)
    • Automating Analysis Workflow
    • Backups of Customer Data
    • Developing Apps and Applets
    • Importing Data
    • Platform Uptime
    • Legal and Compliance
    • Sharing and Collaboration
    • Product Version Numbering
  • Release Notes
  • Technical Support
  • Legal
Powered by GitBook

Copyright 2025 DNAnexus

On this page
  • About Portals
  • Initial Portal Setup by DNAnexus
  • Features of a Portal and Configuration Options
  • Login Page (branding.json)
  • Register Page (branding.json)
  • Header (branding.json and navigation.json)
  • Landing Page (home.json)
  • Managing, Modifying, and Updating Portal Assets
  • Validating JSON files Before Upload
  • Viewing changes in the browser
  • Making Updates via the Command-Line Interface (CLI)
  • Compiling Portal Assets
  • branding.json
  • home.json
  • navigation.json

Was this helpful?

Export as PDF
  1. Administrator

Portal Setup

Learn about Portals and how to set up and use them for your organization.

Last updated 1 year ago

Was this helpful?

A license is required to set up and use a Portal. for more information.

About Portals

A Portal is an org with special privileges that serves two purposes. First, it provides a space for your organization to showcase projects with special data sets, tools that you’ve published, news and highlights or other important links. Second, the Portal has customized branding that will follow the end-user throughout the site with a curated view of projects and tools.

Initial Portal Setup by DNAnexus

We will ask you to provide the initial configuration requirements and assets (logos or other images, brand colors, text, and links) listed below.

Features of a Portal and Configuration Options

This section describes configurations that the Org Admin can make by editing and uploading new .json files or new images.

Login Page (branding.json)

  • Logo (no size limit, but it’s recommended to stay under 200px high)

  • (Optional) Login button color; must be conducive to white text

  • (Optional) Whether to hide the registration link

  • (Optional) Text to display under login button

Register Page (branding.json)

  • Logo (max 100x100px)

  • (Optional) Register button color; must be conducive to white text

  • (Optional) Can disable registration page, redirecting directly back to login

  • (Optional) Markdown text to display under register buttons

  • (Optional) Add default region for users who register with this page

  • (Optional) Add short sentence indicating terms of acceptance

Header (branding.json and navigation.json)

The branding.json controls the colors in the Header. The navigation.json controls the navigation links and menus (with the exception of the logo navigation).

These are the items you can configure:

  • Header corner Logo (min 15x15px, max 50x30px)

  • (Optional) Logo link destination, defaults to Home page (configure in the branding.json file)

  • (Optional) Whether the logo link opens in a new tab (configure in the branding.json file)

  • (Optional) Support page (used when the user clicks on “Get Help” in the Help menu, default is DNAnexus Support Form)

  • (Optional) Color for the nav underbar, text, background, nav hover background color, landing page button color and color array for the user bubble. Currently icons do NOT change color, so do not make the background bar a dark color or text will not be visible.

  • (Optional) Navigation customization. You can add custom items to the ends of our Projects, Tools, and Help menus, remove those menus entirely, or add new menus and links to the nav header.

  • (Optional) Filters for the projects list (i.e. when the user clicks on “All Projects” in the Projects menu)

  • (Optional) Whether to hide the community switcher (this will “lock” the user into the current community)

Landing Page (home.json)

The main page is a customizable landing page with the ability to showcase in any order with any amount of widgets:

  • Specific projects

  • Specific tools

  • Links to external websites

  • Images (PNG, JPEG, TIFF, BMP, etc)

  • Markdown text

The home.json file contains a list of widgets to display, and the order in which to display them.

Text Widget

  • Title

  • id property of “markdown”

  • Minimum width

  • Markdown text

Image Widget

  • Minimum width

  • id property of “image”

  • Image resource or location (image can be any type, e.g. PNG, JPEG, TIFF, BMP)

  • Alt text (when image can’t be displayed)

Link List Widget

  • Title

  • id property of “link”

  • Minimum width

  • List of link destinations and their titles

Project List Widget

  • Title

  • id property of “project” or “projectCards”

  • Minimum width

  • Project sub-page destination

Tool List Widget

  • Title

  • id property of “tool”

  • Minimum width

Managing, Modifying, and Updating Portal Assets

Portal assets are stored with the json files. You can easily upload json and PNG files using the GUI on the main portal home page. The sections for each json file describe the access permissions that each file requires.

The UI can become disabled if a flawed json is inadvertently uploaded. Review the section below on how to validate json files.

Validating JSON files Before Upload

Viewing changes in the browser

It is mandatory to clear your browser cache after updating your portal assets with a revised JSON file.

In most browsers, you can clear the cache from the Privacy or History area in the Settings or Options menu, depending on the browser. The hotkey combination Ctrl+Shift+Del (or Cmd-Shift-Del on a Mac) works with most browsers as well.

While that hotkey combo works in most non-mobile browsers, the exact steps involved in clearing your browser's cache depend entirely on what web browser you're using. If these suggested steps do not work please refer to your browser’s documentation.

As an alternative to clearing your cache, it is possible to use ‘private’ browsing (a.k.a ‘privacy’ mode or ‘incognito’ mode) to view the asset updates. This is a privacy feature in some web browsers to disable browsing history and the web cache allowing a person to browse the Web without storing local data that could be retrieved at a later date. To launch your browser in ‘incognito’ mode, please refer to your browser's documentation.

Making Updates via the Command-Line Interface (CLI)

Compiling Portal Assets

Portal assets are split into many different files, all loaded at different times by different components. Below are samples of each file. Note that several of these files contain references to images; for communities, you can either prepend a pound sign (#) to denote an image fetched from the community assets (e.g. “#logo.png” would fetch the file “logo.png” stored in the community), or you can use a normal URL to fetch an image from an external source.

branding.json

This file must be public (viewable by all users) Applies to the header and community selector, as well as the login and registration pages. colors is optional in each section and contains information about how to change the colors of various elements in the given section.

Earlier versions of Portals had two additional files -- login.json and register.json' -- you do not need to remove those, but all of their information will need to be transferred to branding.json.

In the header, logoOpensNewTab is optional and if true will open a new tab when the user clicks on the logo in the upper left. hideCommunitySwitch is also optional and, if true, will hide the community selector in the upper left (essentially locking the user into the current community).

In the login and registration sections, logo specifies a logo to be used at the top of the given page and text can be Markdown which will be rendered at the bottom of the page (below the button but above the footer).

The registration section has several optional attributes. First, disable, which if true will hide the “Create Account” link on the login page and redirect the user to the login page if they try to manually visit the registration page. There’s also an optional agreeToText attribute, which will be a plain text string (not Markdown) with a checkbox which the user needs to agree to before they can register. It also has an optional region attribute which, if set, will force any user created with this login page to have the given default region instead of presenting them with an option.

homeURL and supportURL are optional and are the URLs used for the main community site (destination when clicking on the logo in the upper left) and support pages (destination when a user selects “Get Help” from the Help menu), respectively. description is shown in the community selector menu.

Note that any logo images defined here must be uploaded with public permissions--logos for the login and registration pages in particular will need to be downloaded by unauthenticated users.

{
 "header": {
   "logo": "#logo_header.png",
   "logoOpensNewTab": true,
   "hideCommunitySwitch": true,
   "colors": {
     "background": "#123456",
     "border": "#123456",
     "text": "#123456",
     "hoverBackground": "#123456",
     "userColors": ["#123456", "#234567", "#345678"],
     "button": {"success": {"border-color": "green", "background":
      "pink", "hover": {"background": "dusk"}}}
   }
 },
 "login": {
   "logo": "#logo_login.png",
   "text": "#Title\n\nThis is Markdown text.",
   "colors": {
     "loginButton": "#123456"
   }
 },
 "register": {
   "disable": true,
   "logo": "#logo_register.png",
   "text": "#Title\n\nThis is more Markdown text.",
   "agreeToText": "Plain text you need to agree to before registering",
   "region": "aws:us-east-1",
   "colors": {
     "registerButton": "#123456"
   }
 },
 "homeURL": "http://example.com",
 "supportURL": "http://example.com/support",
 "hideCommunitySwitch": true,
 "description": "A short description of two or three lines for the community selector"
}

home.json

This file must be at least accessible to community members.

{
 "order": ["hero-image", "featured-projects", "featured-tools", "reference-links", "help-text"],
 "components": {
   "help-text": {
     "type": "markdown",
     "id": "help-text",
     "title": "Useful Advice",
     "content": "# Always wear sunscreen\nIt’s really important.",
     "minWidth": "400px"
   },
   "unused-table-component": {
     "type": "markdown",
     "id": "unused-table-component",
     "title": "A table for you",
     "content": "| Tables | Are | Cool  |\n| --- | --- | --- |\n| a | b | $1600 |\n| c | d | $12 |\n| e | f | $1 |",
     "minWidth": "100px"
   },
   "hero-image": {
     "type": "image",
     "id": "hero-image",
     "src": "#my_awesome_image.png",
     "alt": "Heroes are great"
   },
   "unused-image": {
     "type": "image",
     "id": "unused-image",
     "src": "https://example.com/image.png",
     "alt": "Alt text"
   },
   "reference-links": {
     "type": "link",
     "id": "reference-links",
     "title": "Help and News",
     "links": [
       {
         "name": "Getting Started",
         "subname": "First steps with your new account",
         "href": "https://www.dnanexus.com",
         "icon": "fa-question-circle"
       },
       {
         "name": "Some Helpful News or Docs Link",
         "subname": "Come here for useful information",
         "href": "https://www.dnanexus.com",
         "icon": "fa-question-circle"
       }
     ],
     "footer": {
       "name": "Visit Help Center...",
       "href": "https://www.dnanexus.com/help"
     },
     "minWidth": "300px"
   },
   "featured-projects": {
     "type": "project",
     "id": "featured-projects",
     "title": "Featured Projects",
     "query": {
       "tags": "community-tag",
       "limit": 5
     },
     "columns": [
       {
         "property": "name",
         "label": "Name"
       },
       {
         "property": "modified",
         "formatter": "date",
         "label": "Modified"
       },
       {
         "property": "createdBy.user",
         "formatter": "userHandle",
         "label": "Created By"
       }
     ],
     "viewMore": "/panx/communities/communityname-without-org/projects",
     "minWidth": "400px"
   },
   "featured-tools": {
     "type": "tool",
     "id": "featured-tools",
     "title": "Featured Tools",
     "query": {
       "category": "community-tag"
     }
   },
   "project-destination": {
     "type": "projectCards",
     "id": "project-destination",
     "title": "Project Destinations (Samples)",
     "destination": "samples",
     "query": {
       "properties": {
         "dashboard_config_project": true
       }
     },
     "minWidth": "400px"
   },
 }
}

navigation.json

This file must be at least accessible to community members. Applies to the header. _filters is optional and contains information about how to alter the query sent to the server to fetch the main and featured lists of projects. _projects, _tools, and supportURL are all optional and can be:

  • null to remove the item from the header

  • An array of objects with the following format to add items to the end of the corresponding menu:

    • text is the text of the menu item

    • url is the destination to take the user to

    • newTab is optional and indicates that the link should be opened in a new tab

Any other entries in this file will indicate new navigation items to be added. These are defined by a key (in the example below, “A New Menu” and “A New Link”), and can be either an object with url and optional newTab values (in which case it will be rendered as a simple link in the navigation header), or as an array of objects with keys text, url, and optionally newTab (in which case it will be rendered as a dropdown menu with the listed items).

{
 "_filters": {
  "projects": {
    "featured": {
      "id": ["project-1234", "project-2345"]
    },
    "all": {
      "tags": "community-demo",
      "billTo": "org-demo"
  }
 },
 "_projects": null,
 "_tools": [
  {"text": "Custom Menu Item", "url": "http://example.com"},
  {"text": "Opens in New Tab", "url": "http://example.com", "newTab": true}
 ],
 "_help": null,
 "A New Menu": [
  {"text": "New Menu Item", "url": "http://example.com"},
 ],
 "A New Link": {"url": "http://example.com", "newTab": true}
}

To configure a new Portal for your org you will work with the . First, the Partner will need to specify the org that will host the Portal. The Portal is tied to exactly one org.

Once all configuration requirements and assets have been provided, the Portal will be ready to test. At this point the will provide a link to the Portal along with a brief training to orient the Org Admin to using the portal.

Project filter criteria - To have projects displayed here, set up a search using the API method. Note that if you want all projects to be visible to all users who can access the Portal, set the level parameter to "VIEW."

Tool filter criteria - To have available tools displayed here, set up a search using the API method.

A list of icons available to use on home.json is available . DNAnexus supports the use of icons introduced in version 4.3 and earlier.

JSON (JavaScript Object Notation) is a lightweight data-interchange format. Most of the time, it is easy for humans to read and write but sometimes, it is extremely difficult to actually read and make sense of. We highly recommend validating your portal asset using tools such as or , before using them to update the community portal.

DNAnexus can also provide you with CLI scripts to update your assets. This provides an alternative to the UI, which can become disabled if a flawed json is inadvertently uploaded. Contact for more information and to request access to the scripts for CLI updating.

DNAnexus Professional Services team
DNAnexus Professional Services team
here
jsonlint
jsonformatter
support@dnanexus.com
Contact DNAnexus Sales
Portal Home
Example of adding items to the Tools menu
Example of adding extra navigational links or menus. Also shows recoloring text and highlight.
File Upload
system/findProjects
/system/findApps