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
Quip for Confluence is compatible with Confluence Server and Data Center editions.
Prerequisites
Please ensure all Confluence nodes permit outbound traffic to https://platform.quip.com or your custom Quip URL.
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
The Quip integration plugin has been tested against Confluence 7.19.8. The DBMS used for testing was PostgreSQL 13.5.
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.
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.
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.
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).
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.
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.
Pull out a specific piece of content from a Quip document.
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.
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.
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.
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.
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)
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.