Exporting Collections

Collection exports back up a collection's content as a .zip file you can act on downstream, whether that's a business continuity plan or publishing content to another system. This guide sets up an export process you can automate through an iPaaS tool such as Zapier or Workato.

Step 1: Capture a list of your collections

Using your user token, list the collections you have access to. Depending on how many there are, you may need to paginate through the results.

curl -u $GURU_USER:$GURU_TOKEN https://api.getguru.com/api/v1/collections

Step 2: Configure a trigger in your workflow

There are many ways to do this step. The screenshots below show Zapier and Workato.

Zapier Instructions

Workato Instructions

Step 3: Initiate your collection exports

Loop through your collection list and make a POST call to the collection export endpoint for each:

curl -X POST https://api.getguru.com/api/v1/collections/{collectionId}/export/advanced \
  -u $GURU_USER:$GURU_TOKEN \
  -H "Content-Type: application/json" \
  -d '{
    "notificationEndpoint": "{your webhook URL}",
    "type": "export-collection"
  }'

This kicks off a job that exports the collection into a .zip file. When the job is complete, Guru notifies the webhook URL you specified with a payload like this:

{
  "exportUrl": "https://content.api.getguru.com/files/dn/600f7a86-ea60-4580-b0ff-ce46c457e780",
  "status": "EXPORTCOMPLETE",
  "collection": {
    "name": "Customer Support",
    "id": "6990ea4d-9c40-449b-8666-0eaf41d225df",
    "color": "#FF8A65",
    "assistEnabled": "false",
    "description": "Knowledge support agents need to be helpful resolving issues, managed by the Support Leadership team.",
    "collectionType": "INTERNAL",
    "dateCreated": "2022-02-09T22:02:00.599+0000",
    "collectionTypeDetail": "FRAMEWORK",
    "slug": "vrl13/Customer-Support",
    "roiEnabled": "false",
    "publicCardsEnabled": "true"
  },
  "jobId": "97c9da7f-fa42-427c-b6c7-307b1f3f5981",
  "querystring": null
}

Step 4: Download the exported collection

The exported collection is stored at the exportUrl. Call that URL to download the .zip file, authenticating with the same credentials you use for any other Guru API endpoint.

curl -u $GURU_USER:$GURU_TOKEN -O {exportUrl}

Once you have the .zip file, you can do anything you'd like with it, such as uploading it to Google Drive or publishing its content to an external site.

Export file structure

The .zip contents mirror the import format:

/
  cards/
    card1.yaml
    card1.md
    card2.yaml
    card2.html
  folders/
    folder1.yaml
    folder2.yaml
  resources/
    Image1.png
    mycoolsalesdeck.pdf
  collection.yaml

A collection.yaml file in the root directory summarizes the tag and tag category information:

Tags:
- Tag1
- Category:Tag2

Individual cards live in the cards/ directory. Each card has a metadata file (.yaml) with the card's title and tags, and a content file in markdown (.md) or HTML (.html) with the same file name:

card1.yaml:

Title: Card Title
Tags: 
    - Category:Tag1
    - Tag2
    - Tag3

card1.md:

# Markdown header

And whatever content you want
This is read
In
Raw
So all
Newlines
Are preserved

Cards, folders, and resources reference each other with regular link syntax, using the directory name and ID as the link:

# Markdown

This is a [card link](cards/card1) and this is a [folder link](folders/folder1)

This is an image:

![Alt Text](resources/image1.png)

This is a PDF link
[PDF link](resources/mycoolsalesdeck.pdf)

Folders are YAML files listing their contents:

Title: Folder Title
Description: |
  Multi line
  Description
  here
Items:
- ID: "card1"
  Type: "card"
- Type: "section"
  Title: "My Section"
  Items:
  - ID: "card2"
    Type: "card"