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
  • Workflows and Global Workflows
  • Global Workflow Use Cases
  • Step 1: Build a Local Workflow
  • Step 2: Make the Workflow Global
  • Download the Original Workflow
  • Build a Global Workflow
  • Describe and Run the Workflow
  • Step 3: Add Authorized Users or Orgs
  • Step 4: Publish a Version to Users
  • The "Default" Alias
  • Next Steps
  • Add Developers
  • Create a New Version
  • Delete
  • Discovering Global Workflows
  • Searching Available Versions
  • Searching by Category
  • Summary

Was this helpful?

Export as PDF
  1. Developer
  2. Workflows

Versioning and Publishing Global Workflows

Learn how to create both a local, project-based workflow, and a versioned, global workflow that can be published and listed in the Platform Tools library.

Last updated 14 days ago

Was this helpful?

Workflows and Global Workflows

created on the DNAnexus Platform with an ID in the form of workflow-xxxx are data objects stored in a project.

Because they are stored in a project, it's easy to share the workflow with other users by adding them to the project. These local workflows are great for fast iterations for development and testing. You can always delete the workflow and create a new one in its place.

A global workflow is an executable that can be versioned and published to other users. It is implemented as a wrapper around an existing project-based workflow. For users and organizations collaborating on multiple private or public projects, these local workflows may be less suitable for long-term maintenance and collaboration.

For example, an organization administrator or workflow developer may want to restrict execution of a particular workflow to specific users and organizations, or they may want to allow execution of this workflow across cloud regions and providers. can be used for those use cases and more.

Global Workflow Use Cases

Global workflows offer several key benefits, including:

  • Version Management: Enables tracking and maintaining different versions of a workflow's source code.

  • Provenance & Immutability: Provides an explicit history of changes to the workflow name and associated ID. Each version is immutable, allowing users to revert to previous states while ensuring data integrity.

  • Collaboration & Sharing: Facilitates collaborative development across projects and organizations. Workflows can be shared with authorized users who have execution privileges but cannot modify the core workflow definition.

  • Multi-Region Support: Allows deployment and execution of a single workflow executable across multiple geographic regions and cloud providers.

  • Immutability Guarantees: Prevents modification or overriding of existing workflow versions, ensuring consistency and predictability.

  • Tools Library Integration: Enables authorized users and developers to discover shared global workflows within the DNAnexus Tools Library.

Step 1: Build a Local Workflow

The easiest way to build a workflow is by using the web interface. In your project's Manage tab, click Add > New Workflow. For details, see Building and Running Workflows.

Step 2: Make the Workflow Global

Download the Original Workflow

dx get "Exome Analysis Demo:Exome Analysis Workflow"

This creates a local directory "Exome Analysis Workflow" with the dxworkflow.json file in it.

Build a Global Workflow

Adjust the downloaded dxworkflow.json before you create a new global workflow.

  • Global workflows require the name and version fields.

    • The name has to be unique in the global namespace shared by apps and global workflows.

    • The name can use lowercase letters, numbers, - , . , and _ , and must not contain spaces.

  • You can add fields such as title and summary to make the workflow more user-friendly.

  • You can leave the stages and any other fields unchanged.

dxworkflow.json
{
  "name": "my_global_workflow",
  "title": "Exome Analysis Workflow", 
  "version":"1.0.0",
  "stages": [...]
}
# Create your global workflow
dx build --globalworkflow "Exome Analysis Workflow"

Because Exome Analysis Workflow is the name of the directory storing the dxworkflow.json, it can be changed freely.

Describe and Run the Workflow

The dx build command returns the unique ID of the created version, such as globalworkflow-xxxx .

You can use the ID to refer to the global workflow.

dx describe globalworkflow-xxxx

Running a global workflow is the same as running any other workflow.

dx run my_global_workflow \
  -i0.reads_fastqgzs="Exome Analysis Demo:/Input/SRR504516_1.fastq.gz"

Step 3: Add Authorized Users or Orgs

The users will be able to find and access the global workflow only after the workflow is published. The list of users can be updated by developers before or after it is published, and it will apply to all to the versions of the workflows, past and future.

# Share the workflow with a user AND with an organization
dx add users my_global_workflow user-bob org-partnerorg

# View who's on the workflow's access list
dx list users my_global_workflow

# Remove a user from the access list
dx remove users my_global_workflow org-partnerorg

The authorized user permissions do not propagate to apps automatically. If the workflow contains any apps, the users need access to those apps in order to run the workflow. To add users to an app, you can use the same dx add users command.

Step 4: Publish a Version to Users

Once you've tested the workflow version, you can release it to the authorized users using dx publish .

dx publish my_global_workflow/0.0.1

Publishing a workflow version has the following effects:

  • The authorized users can discover the version via dx find globalworkflow .

  • The authorized users can describe and run the version.

  • The authorized users can download the workflow's dxworkflow.json source code with dx get (as well as the dependencies, e.g. applets), though they cannot build new versions with the same global workflow name.

The "Default" Alias

The "default" alias indicates that this version will be invoked whenever the workflow name is used without specifying a version. For example, users can run the workflow:

dx run my_global_workflow   # equivalent to "dx run my_global_workflow/0.0.1"

The first created version of a global workflow gets "default" flag automatically.

Next Steps

Add Developers

You can enable multiple users to update the current version or build new versions of the global workflow.

# Add a user to the workflow's developer list
dx add developers my_global_workflow user-eve

Either specific users or whole orgs can be developers of a global workflow.

# See who's on the workflow's developer list
dx list developers my_global_workflow

# Remove a user from the developer list
dx remove developers my_global_workflow user-bob

Create a New Version

You can create a new version of the workflow by updating the dxworkflow.json and using dx build --globalworkflow. To create the new version, you need to explicitly update the version string, for example, to "0.0.2".

If you lose the source dxworkflow.json, you can download it at any time using dx get .

# Download dxworkflow.json for a specific version of a global workflow 
dx get globalworkflow-my_global_workflow/0.0.2

Any developer of the workflow can download its source code and build new versions. Authorized users that have access to published versions can only download or run it.

Delete

You can mark a global workflow version as deleted, which will make the version unrunnable. It will still be possible to describe the workflow for provenance purposes.

dx api globalworkflow-xxxx delete

Use with caution

  • Deleting a global executable can break users' reproducibility requirements.

  • Deleting all workflow versions will not release the workflow name. It will not be possible to reuse the name for a different global workflow by another user.

Discovering Global Workflows

Searching Available Versions

# List the current default versions of published global workflows  
dx find globalworkflows

# List the complete version history of published global workflows
dx find globalworkflows --all

# List the global workflows that are not published
dx find globalworkflows --unpublished --all

Searching by Category

You can add the --category parameter to restrict the search to a specific category.

Common categories are available as tab completions. For example:

dx find globalworkflows --category Variation\ Calling

To view all available categories you can search by:

dx find globalworkflows --category-help

Summary

The following table summarizes the main steps and stages required to create and publish the workflow.

Object name
ID prefix
Namespace
Access
Definition and purpose

Workflow

workflow

Project

based on project permissions

A file-like workflow object stored in a project; used for private, light-weight development

Global workflow unpublished

globalworkflow

Global

developers

A development version of a workflow that is not visible to users but is to developers; used for development and testing in multiple regions, release management, preparation for publishing to users

Global workflow published

globalworkflow

Global

users, developers

A version of a workflow that is available to authorized users

Global workflow deleted

globalworkflow

Global

users, developers

A version (previously published or unpublished) that is not runnable but can be described

You can also use the , dx-toolkit .

For a local workflow you'd like to convert to a global workflow, use the command to download a JSON representation (dxworkflow.json) of the local workflow:

It's a good practice to include documentation in the Readme.md file in the same as the workflow.

If the workflow uses globally available apps or applets from non-, you can use dx build to create your global workflow. Workflows using resources from PHI-enabled projects cannot be built as global workflows due to the project's protective restrictions.

You can specify a list of users with whom you want to share the workflow by using .

Developers can add and remove users and other developers at any time. Adding users to the workflow will give the users access to all the published versions but it will have no effect on the unpublished versions. Unpublished versions are only accessible to the people listed as of the workflow.

Executing command makes the published version a default one by adding a "default" alias to this version (and removing it from whichever workflow version was previously marked as "default").

You can use the command to browse the global workflows available to you.

Workflows
Global Workflows
DNAnexus SDK
developers
directory
PHI projects
dx get
dx add users
dx publish
dx find globalworkflows