Skip to main content

Project Import/Export

Export​

Via the Client​

  1. "Project Settings"
  2. Select "Export This Project" and the download will start automatically

Via the CLI​

  1. tsg init
  2. Select the project to export
  3. tsg export

An export-<ID>.zip file will be created in the same directory.

Via the API​

Projects may be exported through their GraphQL API. Exports run in the background. When the export is complete, you'll be given a download URL for the ZIP file containing your project. Most exports should happen within a few seconds, but more complex projects may see longer export times.

You can run your export from anywhere you can make a GraphQL query. This means you're able to create exports from your project's API Explorer, from within your application, or with a script file.

Since they happen in the background, exporting your project is a two step process:

  1. You'll trigger the export by using the tsExportProject mutation. The mutation will return the export id as a string. You may opt to export your project's structure without its data by providing the empty: true argument.
  2. You'll check for the export's download URL by using the tsGetProjectExport query. The query will requires the export ID you obtained in the previous step. While the export is running, the status field will be "running" and the file field will be null. When the export completes, status will be "completed" and file will contain your download URL.

The project export will be a ZIP file, which you can unarchive locally. After unzipping, you'll find a common set of files:

  • pattern.yml, which contains metadata about your project
  • schema.json, which contains your project's schema
  • data.jsonl, which contains your project's data. If you opt to export an empty project, this file will not be included in your export.
  • roles.json, which contains your project's custom roles if you have any.

Examples​

Run a basic export​

First, you'd trigger your export using the tsExportProject mutation.

mutation {
 id: tsExportProject
}

The mutation would return an export ID as a result.

{
 "data": {
  "id": "jN1EGmDuz"
 }
}

You'd then provide the export ID to the tsGetProjectExport query.

Query

query($exportId: String!) { {
 export: tsGetProjectExport(id:$exportId) {
  status
  file
 }
}

Variables

{
 "exportId": "ziYv9oMbK"
}

When the export is completed, the result will contain the download URL.

{
 "data": {
  "export": {
   "status": "completed",
   "file": "https://s3.amazon.com/…"
  }
 }
}
Run an empty export​

To export an empty project, provide the argument to the mutation.

mutation {
 id: tsExportProject(empty: true)
}

Then, follow the same steps as above to query for your export file.

Import a project​

Via the Client​

Pattern​

Blank Project​

URL​

Upload Zip​

Via the API​

Project zip files can be imported via the API using the tsImportProject mutation. For example:

mutation {
 tsImportProject(name: "My Project", uri: "https://example.com/project.zip")
}

The mutation returns an import ID. You can use that ID to get the status of your import like this:

query {
 tsGetProjectImport(id: "insert import id here") {
  id
  status
  message
  projectId
 }
}

Alternately, if you need somewhere to upload your project zip, you can use the tsUploadProject mutation. The tsUploadProject mutation returns a signed S3 URL. You'll upload your zip by doing a HTTP PUT to that URL with your zip file. After you do this, the project zip will be automatically imported and deleted.

mutation {
 tsUploadProject(name: "project.zip" type: "application/zip") {
  uri
  importId
 }
}

Via the CLI​

The CLI has an import command that accepts two arguments:

  1. A required --from flag tells the command where the project you're importing is located. It can be a URI, like to a project in GitHub, the path to a project zip file on your machine, or the path to a project directory that the CLI will zip up for you.
  2. An optional --name flag provides an override for the name of the project that will be created by the import. Currently, this flag only applies when the import source is a URI, but we're working to support it on local file uploads, as well.
  3. An optional --to flag determines if the import will be created as a new project or merged into the currently linked project. Options are new-project and current-project. Default is new-project.

For example, to import the Shape Books sample project from the takeshape/takeshape-samples repo in GitHub, you would run:

tsg import --from https://github.com/takeshape/takeshape-samples/tree/master/shape-books/pattern