HighQ Integration¶

Follow the instructions on this page to integrate your HighQ environment with ContraxSuite.

Definitions¶

Term	Meaning
(HighQ) File	The file in HighQ Collaborate; a `.doc(x)`, `.pdf`, or `.txt` file.
Document	ContraxSuite’s `Document` model.
HighQ Document	A `HighQ Document` is an object with record of: a HighQ File a corresponding ContraxSuite `Document` an iSheet row (“item”)

Prerequisites¶

Before beginning, you will need:

a HighQ Collaborate account
a HighQ folder containing files, and optionally, subfolders
a destination project in ContraxSuite
access to ContraxSuite’s administrative menus
the values for the API fields and HighQ fields listed below

Field	Description	Deonticity	Hints
Title	A unique and descriptive name for this HighQ Integration Configuration.	Required	N/A
Enabled	Whether or not this HighQ Integration Configuration is active. This can be toggled on an off. Sychronization tasks will not run unless the HighQ Configuration is enabled.	Boolean	N/A
Update Existing iSheet Items?	Whether or not changes to document field values in ContraxSuite should update iSheet rows in HighQ.	Boolean	N/A
Get HighQ files from subfolders?	Whether or not ContraxSuite should get files from subfolders in HighQ.	Boolean	N/A
API Client ID	This is an integer provided by HighQ and unique to every client.	Required	Provided by HighQ.
API Secret Key	This is a string provided by HighQ.	Required	Provided by HighQ.
API Instance URL	This is a URL	Required	Provided by HighQ.
ContraxSuite Project	ContraxSuite will download HighQ files and placec them in this project.	Required	We suggest creating a destination project prior to creating a HighQ Configuration.
Assignee	If specified, ContraxSuite will automatically assign documents to this user.	Optional	N/A
HighQ Site ID		Required	Query parameter. Example: `metaData.siteID=1234`
HighQ Folder ID	ContraxSuite will download documents from this folder.	Required	Query parameter. Example: `metaData.parentFolderID=56789`
HighQ iSheet ID	ContraxSuite will send information to this iSheet.	Required	Query parameter. Example: `metaData.sheetId=123`
Synchronization Frequency (minutes)	ContraxSuite will attempt synchronization at fixed intervals of this many minutes.	Required	N/A
iSheet Column Mapping	Map ContraxSuite fields to iSheet columns.	Required	Save the HighQ Configuration before completing this field. The form used to populate the necessary data must first make an API call to HighQ, and can only do so once the above values (API Client ID, API Secret Key, and API Instance URL) have been saved to the database.

Tip

Query parameters can be found in the URL.

They appear after a question mark ? in the form of field1=value1&field2=value2.
For example, in https://en.wikipedia.org/w/index.php?title=Query_string, we see title=Query_string.

Configuring a HighQ iSheet¶

1. Create an iSheet in HighQ Collaborate.

2. Add a File Link column to the iSheet, as seen below.

3. Add other columns to the iSheet as needed. These will correspond to the DocumentFields of the DocumentType.

Optional: Configure for iSheet choice columns (ContraxSuite Choice Fields)

4. In this example, we’ve created a simple categorization with the letters A, B, C, D, E, and F.

5. The example in the previous step and in this Step 5 contains Choice names in the HighQ iSheet choice column that match verbatim with the ContraxSuite Document Field Choices, but this verbatim matching is not essential.

6. Continue on to Initializing the HighQ Configuration.

Initializing the HighQ Configuration¶

1. Navigate to Admin Site > Integrations: HighQ > HighQ Integration Configurations:

2. Click the button in the top right that says “Add HighQ Integration Configuration”.

3. Initialize the HighQ Configuration. First, populate all the fields shown in the figure below:

4. Next, click the + next to the “iSheet Column Mapping” drop-down at the bottom of the screen. This will create a new iSheet Column Mapping.

5. Initialize the fields in the new iSheet Column Mapping, as shown below. Note: DO NOT ADD ANY HighQ iSheet Column Associations.

6. Save the newly-created iSheet Column Mapping. While it may seem counter-intuitive to save the iSheet Column Mapping without any HighQ iSheet Column Associations, by first saving the entire HighQ Configuration, we make it possible for ContraxSuite to request additional data from HighQ and automatically populate association options.

7. Save the newly-created HighQ Configuration. You will be redirected to HighQ’s API authorization page. After selecting “Allow”, you will be redirected back to the HighQ Integration Configuration list.

8. Continue on to Populating the iSheet Column Mapping.

Populating the iSheet Column Mapping¶

1. Select the newly-created HighQ Configuration from the HighQ Integration Configuration list.

2. For the iSheet Column Mapping field, select the newly-created iSheet Column Mapping and click the edit button.

3. It should take a moment for the form window to load. Because the API information was recorded when saving the HighQ Configuration form, ContraxSuite can now make HTTP requests to HighQ in the background. The loading delay is caused by exactly that; ContraxSuite is fetching a list of the iSheet’s columns and will include them as selectable drop-down options!

4. Populate the HighQ iSheet Column Associations.

5. First and foremost, associate the document_id ContraxSuite Field Code with the File Link iSheet column. We see this outlined by box (1) in Figure 10.

6. The remaining HighQ iSheet Column Associations can be set, as outlined by box (2) in Figure 10. Note that in our example, we use ContraxSuite’s effective_date_ann field code to send the annotation to HighQ.

7. Lastly, configuring iSheet choice columns (ContraxSuite choice fields) requires an additional set of steps. Our example is outlined by box (3) in Figure 10. If necessary, continue on to Populating HighQ iSheet Column Choice Mapping.

8. Once finished, save the iSheet Column Mapping.

Figure 10¶

Populating HighQ iSheet Column Choice Mapping¶

1. ContraxSuite stores its choice options as strings. HighQ stores its choice options as ID numbers. We need to reconcile this difference and associate the two with one another.

2. Refer to Figure 8; using ContraxSuite’s built-in HighQ API client, we can see that the Category column has six choices.

Figure 11¶

3. Using the ContraxSuite choice name as the key and the iSheet choice ID number as the value, complete the HighQ iSheet Column Choice Mapping. Once finished, save everything.

Note

A copy of the Jupyter Notebook shown in Figure 11 can be found in the demo/External Integrations directory in ContraxSuite versions 1.9 and later.