--- title: "Transfer Commands" description: "Effortlessly manage content transfers with Cloud CMS CLI, offering developers control over export/import operations. (Gitana 4.0)" product: "Gitana" version: "4.0" url: "/documentation/gitana/4.0/developers/cli/transfer" --- # Transfer Commands The Cloud CMS command-line tool provides developers with a command-line driven mechanism that allows them to: - export content from Cloud CMS as an Archive - import content into new Cloud CMS environments using that Archive Archives consist of ZIP files that store a full capture of the exported content. Archives may consist of an entire snapshot export or they may be partial (spanning date ranges or changeset ranges in the case of Repositories). The Cloud CMS [Transfer Services](/documentation/gitana/4.0/developers/cli/transfer.md) make it possible for all data stores and object instances to be exported, passified in a ZIP and then imported anew. This service is used to power a number of features within Cloud CMS including Deployment, Publishing, Content Replication and Multi-Zone Content Delivery. While the Transfer Service can be invoked via the REST API or via the user interface, it is also available within the Command Line Client as this provides the greatest service to developers and DevOp teams in terms of incorporating content deployment and migration into their build and deployment pipelines. ## Export ``` cloudcms transfer export --source --group --artifact --version [--vault] [--includeACLs] [--includeTeams] [--includeTeamMembers] [--includeRoles] [--includeActivities] [--includeBinaries] [--includeAttachments] [--startDate ] [--endDate ] [--startChangeset ] [--endChangeset ] [--selectedBranchId ] [--tipChangesetOnly] [--contentIncludeFolders] [--contentIncludeRelators] [--branchIncludeRootChangeset] ``` ### Source Use the `--source` switch to specify one or more resources to be exported. For example, if you wanted to export a project, you would specify a project reference (i.e. `project://{platformId}/{projectId}`). You can specify multiple `--source` switches to export multiple things to export. The only requirement is that the sources must all be of the same type (i.e. `project`). To export a project, you can use a reference like: `project://{platformId}/{projectId}` To export a repository, you can use a reference like: `project://{platformId}/{repositoryId}` To export a branch, you can use a reference like: `branch://{platformId}/{repositoryId}/{branchId}` To export a node, you can use a reference like: `node://{platformId}/{repositoryId}/{branchId}/{nodeId}` ### Archive Use the `--group`, `--artifact` and `--version` switches to specify the archive properties. These properties can then be used to reference the exported archive in the future. ### Includes Use the following flags to specify what ancillary elements to include in the archive: - `--includeACLs` - `--includeTeams` - `--includeTeamMembers` - `--includeRoles` - `--includeActivities` - `--includeBinaries` - `--includeAttachments` ### Replication using Date Ranges The `--startDate` and `--endDate` switches can be used to specify a starting date and ending date for any selected items. Generally, these are used for cases where, say, you're exporting a branch and will use the `--childrenOnly` switch on import. These date switches specify a range of modification dates to be exported and can be used to migrate modified content between environments. ### Replication using Changesets When replicating Repository content between environments, you can also utilize changeset ranges. The `--startChangeset` and `--endChangeset` switches can be used to identify a range of repository changesets to replicate. ### Content Exports When exporting a project or a repository, you can target specific branches by using the `--selectedBranchId` switch. This switch identifies a specific branch (by ID) that you would like to include. By using this switch, you implicitly exclude all other branches. In addition, if you're exporting only a single branch, you can use the `--tipChangesetOnly` flag to tell the exporter to export only the tip (or denormalized view) of the branch. This exports a single changeset that contains the tip view of the branch. The historical changesets for the branch are not exported. This results in a smaller archive and is often preferable for cases where you're simply copying content between environments (or pulling down content for ingestion). When the `--tipChangesetOnly` switch is used, you can additionally specify the following: - `--contentIncludeFolders` to have the exporter include any parent folder hierarchies for any exported nodes. With this switch set, the parental folders containing any nodes will also be exported, allowing the content to be situated in the same folder tree on the target after import. - `--contentIncludeRelators` to force the inclusion of any relator associations and any related nodes. Many relator associations are modeled as linked relationships and wouldn't normally be included with an export. However, there may be times where you'd like to force the inclusion of those relator structures. This switch allows you to do so. ### Using Snapshots for Point in Time Consistency The Export process can take some time depending on how many things you're exporting and how large they are. As such, it is possible and even expected that content in your branches may change as they are being exported. These changes can sometimes result in inconsistent exports or cause the exporter to fail as it runs. For example, you might have a very large branch with a very large number of nodes. The exporter walks over these nodes and marks them for export. It then walks over the nodes and exports them. If one of those nodes were to be deleted by an editor in between the time it was marked for export and the time when it was actually exported, the exporter will fail with an exception. To solve for this, consider using branch snapshots. A snapshot captures the branch at a specific point in time. The snapshot can then be exported while your editors continue to work on the master branch. When exporting a project, use the `--selectedBranchId` switch to indicate that the snapshot branch should be exported. This allows your editors to continue their work on the master branch (or any other branch) and guarantees that your export will be consistent. ## Examples Suppose we want to export the `master` branch from project `62226556b2fe5f3555db`. We can run this command to find the repository for the project: ```bash cloudcms project info --project 62226556b2fe5f3555db --pretty -light ``` We get back something like this: ```json { "_doc": "62226556b2fe5f3555db", "title": "My Project", "stackId": "4eb2afb1ee2a21b3d027", "datastores": [ { "key": "content", "title": "repository", "datastoreId": "bc616206262bd6813dfa", "datastoreTypeId": "repository" }, { "key": "principals", "title": "domain", "datastoreId": "564dcd18913930faf4b7", "datastoreTypeId": "domain" } ] } ``` The repository ID is `bc616206262bd6813dfa`. We can now read the master branch for the repository: ```bash cloudcms repository read-branch --repository bc616206262bd6813dfa --branch master --pretty ``` You might get back something like this: ```json { "_doc": "24b3131bd87a4cc4a9cf", "root": "0:root", "tip": "44:95f85022da145981fc85", "title": "master", "type": "MASTER", "archived": false, "snapshot": false } ``` The branch starts at changeset `0:root` and the tip is currently at changeset `44:95f85022da145981fc85`. Now, let's create a snapshot at the tip changeset: ```bash cloudcms repository create-snapshot --repository bc616206262bd6813dfa --changeset 44:95f85022da145981fc85 ``` When that finishes, you'll get back something like this: ``` { "_doc": "7cb195a231c7299e1994", "ok": true } ``` We now have a snapshot branch with ID `7cb195a231c7299e1994`. We can now export the project and tell it to use the snapshot as the selected branch. To export the project, we need to provide a project reference of the structure (`project://platformId/projectId`). To get the platform ID, we can run: ``` cloudcms platform info --pretty --light ``` Which gives back something like: ```json { "_doc": "a270b6f4517d19ccc684" } ``` Thus, we can use a project reference of `project://a270b6f4517d19ccc684/62226556b2fe5f3555db`. We can now run the export like this: ``` cloudcms transfer export --source project://a270b6f4517d19ccc684/62226556b2fe5f3555db --artifact myArchive --group myGroup --version 1.0 --selectedBranchId 7cb195a231c7299e1994 ``` When this finishes, you'll get a report back of the export job that includes start time, completion time, settings and job state: ```json { "_doc": "5610dd3c4ec38b5f742d", "type": "transfer_export", "state": "FINISHED", "started": true, "attempts": 1, "max_attempts": 1, "log_entries": [ { "timestamp": { "timestamp": "20-Jan-2021 21:12:33", "year": 2021, "month": 0, "day_of_month": 20, "hour": 21, "minute": 12, "second": 33, "millisecond": 741, "ms": 1611195153741, "iso_8601": "2021-01-20T21:12:33-05:00" }, "type": "STATUS", "message": "Job Dispatcher started job" } ], "progressMax": 100, "progressCurrent": 100, "asynchronous": false, "sources": [ [ { "typeId": "platform", "id": "a270b6f4517d19ccc684", "ref": "platform://a270b6f4517d19ccc684", "key": "platform_a270b6f4517d19ccc684" }, { "typeId": "project", "id": "62226556b2fe5f3555db", "ref": "project://a270b6f4517d19ccc684/62226556b2fe5f3555db", "key": "project_62226556b2fe5f3555db", "title": "ABC" } ] ], "archiveProperties": {}, "runAsPrincipalId": "cbf6629f4dbb22773236", "runAsPrincipalDomainId": "default", "vaultId": "394a0145f4408d6d55c5", "archiveGroup": "myGroup", "archiveArtifact": "myArchive", "archiveVersion": "1.0", "platformId": "a270b6f4517d19ccc684", "configuration": { "selectedBranchId": [ "7cb195a231c7299e1994" ], "includeACLs": false, "includeTeams": false, "includeTeamMembers": false, "includeRoles": false, "includeActivities": false, "includeBinaries": true, "includeAttachments": true, "artifactParts": [], "artifactIncludes": [], "forceIncludes": false, "branchIncludeRootChangeset": true, "platformId": "a270b6f4517d19ccc684" }, "submitted_by": "cbf6629f4dbb22773236", "submitted_timestamp": { "timestamp": "20-Jan-2021 21:12:33", "year": 2021, "month": 0, "day_of_month": 20, "hour": 21, "minute": 12, "second": 33, "millisecond": 687, "ms": 1611195153687, "iso_8601": "2021-01-20T21:12:33-05:00" }, "queueMs": 1611195153697, "stopped": true, "started_timestamp": { "timestamp": "20-Jan-2021 21:12:33", "year": 2021, "month": 0, "day_of_month": 20, "hour": 21, "minute": 12, "second": 33, "millisecond": 748, "ms": 1611195153748, "iso_8601": "2021-01-20T21:12:33-05:00" }, "server_timestamp": 1611193963835, "server_thread": "job-thread-1", "server_key": "fdfcae4223814145da85", "phase": "export", "stopped_timestamp": { "timestamp": "20-Jan-2021 21:12:40", "year": 2021, "month": 0, "day_of_month": 20, "hour": 21, "minute": 12, "second": 40, "millisecond": 820, "ms": 1611195160820, "iso_8601": "2021-01-20T21:12:40-05:00" } } ``` The job state is `FINISHED` which indicates that the job completed successfully. We can now list the archives in the vault: ```bash cloudcms vault list-archives --vault primary --pretty ``` And you'll see the archive listed. It might look something like this: ```json { "rows": [ { "group": "myGroup", "artifact": "myArchive", "version": "1", "type": "project", "_doc": "a3d0c170922081b5244a", "contentType": "application/zip", "length": 5374053, "_info": { "length": 5374053, "type": "application/zip" } } ], "total_rows": 1, "offset": 0, "size": 1 } ``` We can now download this archive: ```bash cloudcms archive download --group myGroup --artifact myArchive --version 1.0 ``` The archive will be downloaded and saved as `myGroup-myArchive-1.0.zip`. We can now create a new project using this very archive. To do so, we need to pass in the reference to the archive. The archive reference is of the form `archive://platformId/vaultId/archiveId`. Thus, we can do: ```bash cloudcms platform create-project --title "My Second Project" --type archive://a270b6f4517d19ccc684/primary/a3d0c170922081b5244a ``` And we'll get back a response that indicates how the project creation went: ```json { "_doc": "cb71894fa043c4ec49e5", "type": "create-project", "state": "FINISHED", "started": true, "attempts": 1, "max_attempts": 1, "log_entries": [ { "timestamp": { "timestamp": "20-Jan-2021 21:57:34", "year": 2021, "month": 0, "day_of_month": 20, "hour": 21, "minute": 57, "second": 34, "millisecond": 204, "ms": 1611197854204, "iso_8601": "2021-01-20T21:57:34-05:00" }, "type": "STATUS", "message": "Job Dispatcher started job" }, { "timestamp": { "timestamp": "20-Jan-2021 21:57:41", "year": 2021, "month": 0, "day_of_month": 20, "hour": 21, "minute": 57, "second": 41, "millisecond": 567, "ms": 1611197861567, "iso_8601": "2021-01-20T21:57:41-05:00" }, "type": "STATUS", "message": "Finished" } ], "progressMax": 100, "progressCurrent": 100, "asynchronous": false, "runAsPrincipalId": "cbf6629f4dbb22773236", "runAsPrincipalDomainId": "default", "platformId": "a270b6f4517d19ccc684", "project-object": { "title": "My Second Project", "projectType": "archive://a270b6f4517d19ccc684/primary/a3d0c170922081b5244a", "family": "oneteam" }, "submitted_by": "cbf6629f4dbb22773236", "submitted_timestamp": { "timestamp": "20-Jan-2021 21:57:34", "year": 2021, "month": 0, "day_of_month": 20, "hour": 21, "minute": 57, "second": 34, "millisecond": 69, "ms": 1611197854069, "iso_8601": "2021-01-20T21:57:34-05:00" }, "queueMs": 1611197854202, "stopped": true, "started_timestamp": { "timestamp": "20-Jan-2021 21:57:34", "year": 2021, "month": 0, "day_of_month": 20, "hour": 21, "minute": 57, "second": 34, "millisecond": 209, "ms": 1611197854209, "iso_8601": "2021-01-20T21:57:34-05:00" }, "server_timestamp": 1611193963835, "server_thread": "job-thread-0", "server_key": "fdfcae4223814145da85", "created-project-id": "0873f94d85ec1c1cc9e2", "stopped_timestamp": { "timestamp": "20-Jan-2021 21:57:41", "year": 2021, "month": 0, "day_of_month": 20, "hour": 21, "minute": 57, "second": 41, "millisecond": 574, "ms": 1611197861574, "iso_8601": "2021-01-20T21:57:41-05:00" } } ```