Quip Integration Plugin for Confluence

Owned by Matt Muschol
Last updated: Sept 22, 2023
8 min read

Introduction

The Quip integration plugin is a Confluence plugin developed by Swiftix Software. The purpose of the plugin is to address common issues that occur when manually transferring documents from Quip into Confluence, such as the following:

  • Usability and consistency issues

  • Formatting issues

  • Incomplete documents

  • Missing image attachments

Installation and Configuration

Quip for Confluence is compatible with Confluence Server and Data Center editions.

  • Prerequisites

  • Install the plugin from the Atlassian Marketplace

  • If you are using a private Quip instance, then configure your plugin to point to your private instance

    • Settings->Manage Apps

    • Find the “Quip for Confluence” app in the list of user-installed apps

    • Select the “Quip for Confluence” app

    • Press Configure

    • Configure the Quip URL

      • For example, if your private Quip instance lives at “https://quip-mycompany.com, then please use “https://platform.quip-mycompany.com”.

      • It is important that the “platform” bit is added as it is required for API access through tokens

Plugin Overview

Compatibility

The Quip integration plugin has been tested against Confluence 7.19.8. The DBMS used for testing was PostgreSQL 13.5.

Quip Communication

The Quip integration plugin requires Confluence to be able to communicate with the Quip instance on its API access URL (default: https://platform.quip.com). If there are restrictions on outbound network communication, then please ensure that all Confluence nodes permit outbound traffic to the Quip instance.

Quip Authorisation

The Quip integration plugin uses Personal Quip Tokens for authentication.

Every individual wanting to use the Quip integration plugin functionality needs to authorise access to Quip by generating a Personal Access Token and adding the token in Confluence.

The Quip integration plugin has been designed to guide the user through this process. If a valid token is present, there is no need to generate and store any new tokens. If a valid token cannot be found for the current users, they will see one of the following two messages.

For the Quip Macro:

 

When the user clicks on the link, they are taken to a screen where they find instructions on how to generate a Personal Access Token and can then add the token to Confluence. The Personal Access Token is stored in the Confluence database in an Active Objects table in AES/CBC encrypted format.

Once the token has been saved, the user is automatically returned to the previous page.

Importing Documents From Quip Into Confluence (Static Import)

When you import a document from Quip into Confluence, it translates Quip formatting into Confluence Storage Format. This means that once a document has been imported, you can edit it in Confluence like any other Confluence page.

Note that importing a document is very different from the Quip Macro (see below) in the sense that the connection with Quip is no longer relevant after the import. The document has become a Confluence page and any changes made to the document in Quip after the import are not visible in Confluence, and any changes made in Confluence after the import are not visible in Quip.

If your Quip document has attachments like images, videos, Word documents, PDF files etc, then those attachments are retrieved and turned into Confluence attachments.

To import a document from Quip into Confluence, please follow the steps below:

  • Navigate to the page that you would like to be the parent page for your imported document. The Quip document will be imported as a child of the current page.

  • Find the three-dots menu in the top-right corner

  • Select Import Quip Document (which appears just after Confluence’s Import Word Document). The menu entry is highlighted in the following screenshot in yellow.

 

  • This will open up a new screen, where you enter the ID of your Quip document. You can find the ID in Quip by navigating to the document and copying the ID from the URL. The ID is highlighted in yellow in the following screenshot.

  • When you click on Import Document, it will perform the import process and then take you directly to the imported page.

Using the Quip Macro (Live View)

The live view mode allows a user to create live links to Quip documents in their Confluence pages. When a live link is created, any changes to the Quip document are automatically pulled through every time the page is loaded or refreshed. This means that every time a Confluence page is loaded, the contents of the Quip document at that moment in time are pulled through.

Note that when using the Quip live-view functionality, the Quip document is never imported into Confluence. The only information that lives in Confluence is a reference to the Quip document. For that reason some functionality such as task lists will not work with live view as the task does in fact not exist in Confluence.

Live-view references to Quip documents are inserted using a Confluence macro as follows:

  • Edit the page in question

  • Put your cursor in the place in the document where you would like to insert the Quip document

  • Click on the “+” symbol at the top bar and select Other Macros

  • Search for the Quip Macro

 

  • Click on the Quip Macro

  • In order to import a Quip document, you currently need to know the document ID

  • Insert the document ID and either press the Insert button or click on Preview to preview document contents

  • When you click Insert, the macro is added to your page

When you click Insert, the macro is added to your page.

Once you save the page, the document will display the contents of the Quip document directly in Confluence. A link to the original document in Quip is provided for convenience (opens in new tab).

Search for Documents

You can search for documents by title in the Quip macro by entering a search word and clicking on Search or Preview.

Once you have found the document you would like to use for your macro, you can copy and paste the document ID into the Page ID field.

Anchors

Please note that anchor support is in beta and may not always function as expected. Please see below for know limitations.

The Quip macro allows you to specify an anchor ID to return a specific piece of content from a Quip document. This allows you to pull elements out of a Quip document rather than the full document.

Please note that anchors for the Quip macro are currently known to work with the following elements in Quip:

  • Cells in tables and spreadsheets

  • Images

  • Bullet/number list items

  • Headings

Because of limitations in the Quip API, Anchors for the Quip macro are known to NOT work with the following:

  • Paragraphs

  • Full bullet/numbered list (you can only point to individual items not the full list)

To get an anchor link in Quip, open your Quip document and right-click on the item you would like to link to and select “Copy Anchor Link”. This will copy a link to the clipboard.

The link will look as follows:

https://swiftix-software.quip.com/8R3OAqdy34lo/Sample-Quip-Document#temp:C:AOU8cd955b372e3401386ccbf44d

The anchor ID is everything after the hash “#” character, i.e. temp:C:AOU8cd955b372e3401386ccbf44d in this example.

It is the anchor ID that should be used for the Quip macro.

New Features

v2.1.3

Anchors (Beta) in Quip Macro

Pull out a specific piece of content from a Quip document.

Hiding Banners in Quip Macro

By default the Quip macro will add horizontal lines and a banner to the output received from Quip. The banner provides a link to the original document on Quip.

It is now possible to hide the banner with a new option on the Quip macro.

v2.0.0

Import of Quip Documents

Import documents from Quip and turn them into Confluence content. When Quip documents are imported, they are translated into Confluence Storage Format, which means that you can view and edit them like any other Confluence page. Any attachments on the Quip document are turned into attachments on your Confluence page.

v1.0.2

Attachment Proxying for Quip Macro

If your Quip document contains attachments such as images or spreadsheets, it now uses the Confluence user’s Quip token to retrieve the attachment and proxies it through Confluence.

This means that as long as you have a valid Quip token stored in Confluence, you can view attachments on a page in Confluence without needing to be logged in to Quip separately.

Troubleshooting

Infinite Loop When Adding Personal Token

When a user adds a personal token via the Authorize Quip Access page, they can sometimes be returned to the Authorize Quip Access page again. This usually indicates that the Quip integration plugin was unable to communicate with the Quip instance and a 401 “Unauthorized” response was received.

This can happen if the user copies across the wrong or an outdated token. Note that personal tokens normally remain valid until the user generates a new token.

Note that this error can also occur if Confluence is unable to communicate with Quip. If the issue happens for all users, then it is very likely that there are restrictions on outbound traffic from the Confluence node to Quip.

Resetting A User’s Access Token

There are two options for a user to reset their own access tokens:-

  • Generate a new personal access token with Quip. This will invalidate the current token.

  • Logged on as the correct Confluence user, navigate to <confluence-base-url>/plugins/servlet/quip-for-confluence/unauthorised, which will allow you to set a new token (including an invalid token such as “abcd” for testing purposes)

Data Security and Privacy Statement

Quip for Confluence does not collect, extract, store, transmit or share any data from your Confluence instance.

The only information stored by Quip for Confluence relate to the successful operation of the app and include the plugin configuration and Quip personal tokens, which are all stored in the Confluence database.

For security reasons, Quip personal tokens are stored in the Confluence database in AES-256 encrypted format.