Cloning

You can clone (copy) objects from one data container to another after they reach the "closed" state. This includes copying between projects.

To clone objects, you need:

• VIEW access or higher to the source container

• UPLOAD access or higher to the destination container

• The source container must not have the RESTRICTED flag set

When you clone an object, the system creates an independent copy in the destination container. This copy includes all user-provided metadata and follows the destination container's permissions. The cloned object has no connection to the original—it is a separate, standalone copy.

Removing the original object doesn't affect the clone, and modifying the clone's metadata doesn't change the original object.

API method: /class-xxxx/clone

Specification

This method copies one or more objects and folders from a source container to a destination container. You can optionally specify a destination folder within the target container.

How cloning works

• Basic cloning behavior: Each object is cloned only once, even if it appears multiple times in the input. When you clone a folder, a new folder with the same name is created in the destination, containing copies of all the source folder's contents. The exception is the root folder ("/"): if specified in folders, its contents are copied directly into the destination folder without creating a new subfolder.

• Linked objects and dependencies: The system automatically follows links in cloned objects and includes any hidden objects they reference. This process continues recursively for any linked hidden objects. However, if a linked hidden object exists outside the source container, any objects it links to will not be cloned to preserve data integrity. For applets, any objects listed in the bundledDepends field are automatically included in the clone.

• Folder-specific rules: Hidden objects within a folder are only cloned if a visible parent object is also being cloned. These hidden objects maintain their relative position within the cloned folder structure, while other hidden objects are placed in the specified destination folder.

Object type considerations

• Workflows: The cloning behavior depends on the workflow's state. Open workflows create a new replica workflow object in the destination, while closed workflows are cloned directly to the destination.

• Databases: These cannot be cloned because they belong to a single project. Database objects must be relocated using move operations instead.

• Existing objects: If an object already exists in the destination container, it is skipped during cloning. The skipped object IDs are returned in the exists array. The clone operation succeeds even if some objects are skipped, but you may need to use the /move method to place existing objects in the correct folder.

Archival object restrictions

• Same billing entity requirement: Objects can only be cloned between projects with the same billTo entity when they are in "live", "archival", or "archived" states.

• Transition state limitations: Objects transitioning between archival states (from "archival" to "archived" or in "unarchiving" state) cannot be cloned until the transition completes.

• Cross-billing entity cloning: To clone archival objects between projects with different billTo entities, all objects must be in the "live" state. See archival objects for more details.

Inputs

• objects array of strings (optional, required if folders is not provided) List of object IDs (strings of the form "class-xxxx") in the source container to be cloned

• folders array of strings (optional, required if objects is not provided) List of folders in the source container to be cloned

• project string ID of the destination container

• destination string (optional, default "/") The destination folder in project

• parents boolean (optional, default false) Whether the destination folder and/or parent folders should be created if they do not exist

Outputs

• id string ID of the source container

• project string ID of the modified destination container

• exists array of strings List of object IDs that could not be cloned because they already exist in the destination container

Errors

• InvalidInput

  • objects (if provided) is not an array of nonempty strings

  • folders (if provided) is not an array of nonempty strings

  • Two of the folders in folders have the same name but different paths

  • project is missing or is not a nonempty string unequal to the source container

  • destination (if provided) is not a nonempty string starting with "/"

  • parents if provided is not a boolean

  • project must be in the same region as the source containers of all specified objects.

• InvalidType

  • project is not a container ID

• ResourceNotFound

  • The container specified in the URL does not exist

  • The container specified in project does not exist

  • One or more objects or folder routes in objects and folders were not found or were not in the source container

  • The folder specified in destination does not exist in the destination container)

• PermissionDenied

  • VIEW access is required in the source container

  • UPLOAD access is required in the destination container

  • RESTRICTED flag must not be set in the source container

  • The source and destination containers must have the same region. For more information about regions, see Regions.

• InvalidState

  • One or more of the input objects is not in the "closed" state

  • One or more of the input objects is a database object, or one or more of the input folders contain a database object

  • There exists a folder in the destination folder destination which has the same name as a folder listed in folders

  • The destination project is third-party sponsored and one or more of the input objects is DNAnexus-sponsored

  • The destination project is third-party sponsored and one or more of the input objects is already third-party sponsored in another project. When this error is thrown, the error details is of the form {alreadySponsored: [{id: ..., project: ...}, ...]} indicating the ID and sponsoring project of each object that was already third-party sponsored.

  • Cannot clone one or more objects as they are being archived or unarchived.

  • Cannot clone one or more objects as they are not in the live state, and the source project and destination project belong to different billTo orgs.

  • Cannot clone one or more objects in folder folder as they are being archived or unarchived.

  • Cannot clone one or more objects in folder folder as they are not in the live state, and the source project and destination project belong to different billTo orgs.

• SpendingLimitExceeded

  • The billTo of the destination project has already reached its spending limit and is different from the billTo of the source project

API method: /class-xxxx/listProjects

Specification

Returns a list of projects that contain the object specified and for which the user has permissions to access. If the token is not full scope, the projects that are returned are filtered to those that the token has at least VIEW access to.

Inputs

• archivalInfoForOrg string (optional) The org ID of the organization whose org admin is the requesting user.

Outputs

• key ID of a project that contains the specified object

• value string Permission level that the user has in the project

• liveProjects array of strings (only if archivalInfoForOrg is specified) An array IDs of projects that contain a live copy of the file. Those projects are either the ones requesting user has access to or the ones whose billTo is the org specified by archivalInfoForOrg.

Errors

• ResourceNotFound

  • The specified object does not exist

• PermissionDenied

  • Must be the org ADMIN of archivalInfoForOrg to return archival info