Guru Manual Sync

The Guru Sync platform connects Guru to external content sources. It extracts content from an external source, such as Zendesk Guide or Salesforce Knowledge, and populates it into a read-only collection in Guru, so users can search internal and external content from one place. Synced content cannot be modified in Guru; running the sync again updates it.

The Manual Sync API imports a large amount of content by uploading a .zip file of structured content to a specified endpoint. All content is synced into a single collection: every card, folder, and resource in the directory structure is added to that collection, and every file in the structure can be referenced within it.

Directory structure

The .zip file uses the same structure as the .zip import format:

mycollection.zip:

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

Root directory

The root directory contains all of the content for the collection.

A collection.yaml file in the root defines the items at the top level of the collection, the tags used on cards throughout the collection, and the import framework version. It's important to include Version: 2.

Version: 2
Items:
- ID: "ff62ad51-41d5-48a5-82c6-74c55c183406"
  Type: "card"
- ID: "2bf8cf82-d6f7-4a67-a13e-aa584b4289ab"
  Type: "folder"
- ID: "e6494f50-23d3-41b7-8061-d4e044283554"
  Type: "folder"
- ID: "cd9e3c25-417a-4f1e-a5e4-6d1186749def"
  Type: "folder"
Tags:
    - "Tag1"
    - "Category:Tag2"

Cards

Individual cards are saved in the cards/ directory with a unique file name. Each card has a metadata file and a content file with the same file name and different extensions. The metadata file is .yaml and contains the card's title and any tags. The content file is either markdown (.md) or HTML (.html). Any tag used in an individual card file must also be listed in collection.yaml.

card1.yaml:

Title: "Card Title"
Tags: 
    - "Category:Tag1"
    - "Tag2"
    - "Tag3"
ExternalId: "af133745-aef5-4184-8349-0825e02ffee2"
ExternalUrl: "https://mycoolsite.com/123"

card1.md:

# Markdown header

And whatever content you want
This is read
In
Raw
So all
Newlines
Are preserved
> ok
       Got it?

Folders

Folders are structured YAML files listing the cards and other folders they contain. The order of the items matters. Cards are referenced by their unique file identifier without the extension, and sections can be created at the top level with their own list of cards. The folder's Title is required; Description is optional.

---
Title: "Folder 1"
Description: |
  Multi line
  Description
  here
Items:
- ID: "c76ed336-988d-4047-8f55-e0ebb51daa88"
  Type: "card"
- ID: "39da5092-2014-45ce-8368-91d357f89433"
  Type: "card"
- ID: "fdea89ed-eed0-4d5c-a983-82b5534a0383"
  Type: "card"
- ID: "e586a9ed-8f26-4b00-b3a9-552492a112a1"
  Type: "folder"
- ID: "af133745-aef5-4184-8349-0825e02ffee2"
  Type: "folder"
- ID: "6eff97c3-2c62-49ae-b00c-fd8bfb0afc13"
  Type: "folder"
ExternalId: "56020ddc-34e7-4fff-b22d-27e444678076"
ExternalUrl: https://mycoolsite.com/456

Resources

Images and other resources go in the resources/ directory and are uploaded to Guru. Link to them from card content as described below.

Referencing other cards, folders, and resources

Reference folders, resources, and other cards in card markdown or HTML content with regular link syntax, using the directory name and the card, folder, or resource ID as the link. The importer replaces these references with real IDs during the sync.

To link to card1, reference cards/card1. To link to folder1, reference folders/folder1. For resources, use the resources/ directory and the full file name (for example, image1.png or mycoolsalesdeck.pdf).

# 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)

API implementation

To set up a collection for synced content, first create a target collection whose collectionType is EXTERNAL. You can only set this value when creating the collection, and you must use the API to do it.

curl -X POST https://api.getguru.com/api/v1/collections \
  -u $GURU_USER:$GURU_TOKEN \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My Synced Collection",
    "collectionType": "EXTERNAL",
    "description": "",
    "color": "#F44336",
    "publicCardsEnabled": false,
    "syncVerificationEnabled": false,
    "initialAdminGroupId": "21c9dad5-71ae-41ad-84d6-334054894e44"
  }'

Once the collection exists and the directory structure holds all your content, zip up the directory and POST it to the manual sync endpoint:

curl -u $GURU_USER:$GURU_TOKEN "https://api.getguru.com/app/contentsyncupload?collectionId={collectionId}" \
  -F "[email protected]" -D -

The POST creates a job ID you can use to check the status of the import:

curl -u $GURU_USER:$GURU_TOKEN https://api.getguru.com/api/v1/import/{jobId}/status

{
  "status" : "IMPORTCOMPLETE"
}

If you need help troubleshooting your collection.yaml formatting or a REJECTED status, contact [email protected].

The sync process goes through all of the content, creates the necessary resources, cards, and folders, and makes sure everything is referenced properly (card links, image links, and so on).

How the sync works

A sync replicates the structure as well as the content of the external source, creating folders and cards that mirror the hierarchy in the source system.

• The sync automatically removes any content that is no longer in the external source. This applies to cards and folders: if one is synced into Guru and is absent from the .zip file in a subsequent sync, it is removed from Guru.
• Tags synced into Guru are not removed when they are absent from subsequent syncs.
• To delete a synced collection, contact [email protected] and we will delete it for you.