Community Discussions
Guides

[LEGACY] Guru Manual Sync

Suggest Edits

Overview

The Guru Sync platform connects Guru to external content sources. The feature enables Guru to extract content from an external source and populate that content into a read-only Collection within Guru. This way, Guru users can search both internal and external-facing content from one place.

This further improves team productivity by being able to search for important content without leaving Guru or changing your workflow. All content that is synced into Guru from an external source, i.e. Zendesk Guide, Salesforce Knowledge, custom, will be marked as read only and cannot be modified.

The rest of this document will detail how the Manual Sync API allows a large amount of content to be imported into Guru in an efficient and organized manner. The API involves uploading a zip file of structured content to a specified endpoint. All content is “synced” into a single collection. The full structure of the zip file represents all the content in a single Collection. Every card, board, board group, resource, etc. in this directory structure will be added to the same collection. Every file in the directory structure is considered to be referenceable within the Collection (more on this later when discussing Card content).

Directory Structure

/
  cards/
    card1.yaml
    card1.md
    card2.yaml
    card2.html
  boards/
    board1.yaml
  board-groups/
    board-group1.yaml
    board-group2.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 directory is used to summarize the tag/tag category information in the import. A sample collection.yaml file is below

collection.yaml:

Tags:
- Tag1
- Category:Tag2

The import supports both categorized and uncategorized tags. Categories can be specified by using a colon to separate the category name from the tag name.

Cards

Individual cards are saved in the cards directory with a unique file name. For each card, there is a metadata file and a content file which should have the same file name part with different file extensions. The metadata file is stored in yaml format and contains the card’s title and any tags that should be on the card. The content file can either be markdown (using the .md file extension) or html (.html file extension). For the tags in the metadata file, both categorized and uncategorized tags are supported as described in the collection.yaml section above. It is important that any and all tags in the individual card files be listed in the collection.yaml file.

The card metadata yaml file should also include an ExternalId which is a unique identifier for this card in the external system. This ExternalId is used across imports to perform updates on existing cards rather than creating new cards. Additionally, the import will clean up old cards that weren’t a part of the current import using this ExternalId field. Finally, an ExternalUrl field can be included to reference the URL in the external system that this card is sourced from. This ExternalUrl will be displayed in the Guru UI to easily link back to the source content.

A sample card metadata and content is below:

card1.yaml:

Title: Card Title
Tags: 
    - Category:Tag1
    - Tag2
    - Tag3
ExternalId: 123
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?

Referencing Other Cards, Boards, Board Groups, and Resources

Board Groups, Boards, Resources and other Cards can be referenced in card markdown/html content by utilizing the regular link syntax, but using the appropriate directory name and card/board/board group/resource ID as the actual link. This allows the bulk importer to replace the unique cards/board/groups/resources in the content with the actual IDs during the import process.

To link to card1, reference cards/card1. To link to board1, reference boards/board1. To link to boardGroup1, reference board-groups/boardGroup1. To link to resources, use the resources/ folder and the full name of the resource (ie, image1.png, mycoolsalesdeck.pdf).

# Markdown

This is a [card link](cards/card1) and this is a [board link](boards/board1)

This is an image:

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

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

Boards

Boards can be represented with structured YAML listing cards that are contained in it. The order of the cards matters. Cards are referenced by their unique file identifier without the extension and Sections can be created at the top level that include a list of cards. The board Title is required and the Description is optional.

The board yaml should also include an ExternalId which is a unique identifier for this board in the external system. This ExternalId is used across imports to perform updates on existing boards rather than creating new boards. Additionally, the import will clean up old boards that weren’t a part of the current import using this ExternalId field. Finally, an ExternalUrl field can be included to reference the URL in the external system that this board is sourced from. This ExternalUrl will be displayed in the Guru UI to easily link back to the source content. Please note that the board's yaml file (e.g. board1.yaml) matches its external ID (e.g. ExternalId: %u201Cboard1%u201D).

Title: Board Title
Description: |
  Multi line
  Description
  here
Items:
- ID: "card1"
  Type: "card"
- Type: "section"
  Title: "My Section"
  Items:
  - ID: "card2"
    Type: "card"
ExternalId: 456
ExternalUrl: https://mycoolsite.com/456

If you want to import boards in a certain order, you can provide an itemized list with board titles and IDs in the collections.yaml file. The boards will still each have their own .yaml file in the boards/ folder.

Here is an example of what it could look like:

collection.yaml:

Items:
- ID: '2341443'
  Title: Organizing Content
  Type: board
- ID: '2570865'
  Title: Managing Teams in Guru
  Type: board
Tags: []
Title: test

Board Groups

A Board Group can be represented using a structured yaml file and reference board files that live under the boards/ directory within the current Board Group’s directory. The board group Title is required and the Description is optional.

The board group yaml should also include an ExternalId which is a unique identifier for this board group in the external system. This ExternalId is used across imports to perform updates on existing board group rather than creating new cards. Additionally, the import will clean up old board group that weren’t a part of the current import using this ExternalId field. Finally, an ExternalUrl field can be included to reference the URL in the external system that this board group is sourced from. This ExternalUrl will be displayed in the Guru UI to easily link back to the source content.

Title: Board Group Title
Description: |
  Multiple lines
  Are allowed
Boards:
- board1
- board2
- board3
ExternalId: XYZ
ExternalUrl: https://mycoolsite.com/XYZ

Resources

Images and resources can be saved to the resources/ directory and they will be uploaded to Guru. Images and resources can be linked within card content as described above..

API Implementation

In order to ensure that the Collection is set up for synced content, you first need to set up a target collection for your synced content whose collectionType is EXTERNAL. You can only set this value when creating the collection and you must use our API to do this.

This is done as a POST call to https://api.getguru.com/api/v1/collections with this payload:

{
  "name": "My Synced Collection",
  "collectionType": "EXTERNAL",
  "description": "",
  "color": "#F44336",
  "publicCardsEnabled": false,
  "syncVerificationEnabled": false,
  "initialAdminGroupId": "21c9dad5-71ae-41ad-84d6-334054894e44"
}

Once the collection and the directory structure is created with all of the content, the sync can be executed by simply zipping up the directory and POSTing the content to the manual sync endpoint https://api.getguru.com/app/contentsyncupload with the right credentials.

Sync File Upload Call

curl -u EMAIL:TOKEN https://api.getguru.com/app/contentsyncupload?collectionId=COLLECTION_ID -F "[email protected]" -D -

When POSTed, a job id will be created which can then be used to query the status of the import.

Status Check Call
Sample Request

curl -u EMAIL:TOKEN https://api.getguru.com/api/v1/import/{jobId}/status

Sample Response

{
  "status" : "IMPORTCOMPLETE"
}

status - Indicates the current state of the sync job.

"status" : "IMPORTCOMPLETE" - The sync has completed successfully
"status" : "REJECTED" - The content of the sync was invalid
"status" : "IMPORTHOME" - Indicates that the sync is transitioning on its way to completion. This status should leave that state and become "IMPORTCOMPLETE" fairly quickly. If you still see that the status of your sync is on "IMPORTHOME" for longer than an hour, that usually indicates that they collection.yaml file is either missing or improperly formatted.

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

The sync process should go through all of the content, create the necessary resources, cards, boards, etc. and make sure that everything is referenced properly (card links, image links, etc.)

Details about how the Sync Works

A Sync will replicate the structure as well as the content of the external source, creating Board Groups, Boards, and Cards that mirror the hierarchy in the source system being synced.

  • The Sync process will automatically remove any content that is no longer in the external content source. This applies to Card, Boards, and Board Groups. If a Card/Board/Board Group is synced into Guru and is absent from the zip file in a subsequent sync, it will be removed from Guru.
  • Tags that are synced into Guru are not removed if they are not in subsequent syncs.
  • If you need to deleted a synced Collection, please reach out to [email protected] and we will delete the Collection for you.

Updated about 1 year ago