Configuring a NetDocuments Integration

by Christina Moore Updated May 19, 2020

Gathering Authentication Information

This tutorial will take you through setting up a NetDocuments Integration. There are a few steps in this tutorial that must be completed within a time limit imposed by NetDocuments. To make configuration as easy as possible we have laid out this tutorial so you will have everything you need to complete configuration in time.

Before we begin make sure you are ready to complete the following steps:

  1. Complete a POST request to NetDocuments within a 2 minute window
  2. Fire a Rest Request Action from Onit to NetDocuments within a 20 minute window

First we will configure the Onit side of the integration. While configuring you will see that you need the following information from NetDocuments. Obtaining this information is outlined later in the document.

  1. Encoded Client ID
  2. Encoded Client Secret
  3. Refresh Token

Steps that require any of the information stated above are marked with a yellow header for easy replacement later.

Onit Configuration – NetDocuments App

Create a new App called NetDocuments with the following Fields:

  • name
    • Display name: NetDocuments Integrator
    • Type: Text
  • netdocs_auth
    • Display name: Netdocs Auth
    • Type: Text
    • Liquid calculation:
{% assign access_token = netdocs_response | replace: '\u003C', '' | replace: \u003E | : | split: access_token %}{{access_token[1] | remove: '/' }}
  • netdocs_refresh
    • Display name: Netdocs Refresh
    • Type: Text
    • Liquid calculation:
{% assign refresh_token_temp = netdocs_response | parse_json | split: '3600' %}{% assign final_refresh = refresh_token_temp[1] | split: Bearer %}{{final_refresh[0] | remove: /refresh_token|remove:/expires_inrefresh_token|remove: token_type |url_encode}}
  • netdocs_response
    • Display name: Netdocs Response
    • Type: Text

Replace placeholders with the encoded Client ID and Client Secret.

Create a new Rest Request Action named Get Token

  • URL: https://api.vault.netvoyage.com/v1/OAuth
  • Call: POST
  • Headers: (replace with your base 64 encoded client id and client secret)
Authorization: <ENCODED CLIENT ID AND CLIENT SECRET (E.G., BASIC ABCED...)>
Content-Type:application/x-www-form-urlencoded
  • Body JSON:

On the first run of this Action you will need to hardcode the refresh token you obtained earlier into the body. Once the Action has been run at least once replace the hardcoded refresh token with {{netdocs_refresh}}

Replace placeholder with the refresh token.

grant_type=refresh_token&refresh_token={{netdocs_refresh}}
  • Status Field: Netdocs response

Next create an Action Button to run the Get Token action.

Once you have placed the correct information in the configuration create a new Record and click the button to run the Action, then return to the Get Token Action and replace the hardcoded refresh token. All subsequent token calls will refresh this token (it expires in 60 days if unused).

Onit Configuration – Create the NetDocuments Transaction List Provider

Now that we have configured the NetDocuments App, we need to set up the App as a list provider in Onit. Create a new Transaction List Provider with the following Fields:

  • Name: NetDocuments
  • App: NetDocuments
  • Atom Columns:
    • [NetDocuments] NetDocs Auth (netdocs_auth)
    • [NetDocuments] NetDocuments Integrator (name)

Onit Configuration – Create the REST Request Action (Matter App)

Now we will configure the iFrame. To begin we will need to find the client workspace GUID and the cabinet number to make the REST Request URL.

To retrieve the client workspace GUID login to your NetDocuments vault page (https://vault.netvoyage.com/neWeb2/docCent.aspx) then select Admin from the username drop down in the top right.

The URL on the next page will contain the GUID.

To get the Cabinet ID Number go to to Profile attributes from the Navigation menu

Then find the appropriate cabinet. The cabinet number will be the last two digits of the id.

To create the iFrame navigate to the App you would like the iFrame to display in, here we will use the Matter App.

Create a new Rest Request Action with the following information:

  • URL: https://api.vault.netvoyage.com/v1/attributes/<CLIENT_WORKSPACE_GUID>/<CLIENT_CABINET_NUMBER>
  • Call: PUT
  • Headers
Authorization:Bearer {{ NetDocuments Integrator | list_lookup: NetDocuments, name, netdocs_auth}}

Content-Type:application/json
  • Body JSON:
{
"defaulting": "",
"description": "{{name}}",
"hold": true,
"key": "{{number}}"
}

Onit – Configure the iFrame Panel

The final thing we need for this integration on the Onit side is the iFrame window. In the Matter App navigate to App Panels and create a new iFrame.

Name: NetDocs

Height: 700

URL:

https://vault.netvoyage.com/neWeb2/goId.aspx?ws={{number}}&cabinet=<CABINET_GUID>&smallDisplay=F

Notice a few things here:

  • ws = workspace key
  • cabinet = specific client cabinet GUID, not the cabinet ID number (see below)
  • smallDisplay = F (changing this from 'F' to 'R' or other options from NetDocs will change the display type, such as full or mobile modes)

You can find the cabinet GUID by navigating to the admin page in the NetDocuments Admin Console and selecting the appropriate cabinet.

The cabinet GUID will appear in the cabinet URL.

You have completed the Onit side of this integration.

Gathering NetDocuments Information

The following steps will walk you through obtaining the Client ID, Client Secret, Redirect URI, and Additional Redirect URI's (optional).

First, login to the NetDocument Partner Community (https://netdocuments.force.com/login). From the Home page click the Accounts tab.

Click 'Onit, Inc'

Scroll down to 'Applications' and find the correct application in the list and click 'Edit'.

From here, grab these four items.

Client ID (I.E. “AP-1234ABCD”)

Client Secret (I.E. “abcdefghijklmnopqrstuvwxyz123456890”)

Redirect URI (I.E. https://www.onit.com)

(Optional) Additional Redirect URIs (I.E. http://localhost/)

Encoding the Authorization Header

Now that you have the client ID and client secret, we'll need to encode them to make the Authorization Header.

To create this header join your Client ID and Client Secret with a ':'

For example:

Client ID of  “AP-1234ABCD”

Client secret of “abcdefghijklmnopqrstuvwxyz123456890”
Resulting plain-text header: AP-1234ABCD:abcdefghijklmnopqrstuvwxyz123456890

Next take this plain-text header and encode it using https://www.base64encode.org/

Take the resulting encoded header and prepend it with 'Basic'.

The authorization header value would then be:

Basic QVAtMTIzNEFCQ0Q6YWJjZGVmZ2hpamtsbW5vcHFyc3R1dnd4eXoxMjM0NTY4OTA=” 

and the full authorization header would be

Authorization: Basic QVAtMTIzNEFCQ0Q6YWJjZGVmZ2hpamtsbW5vcHFyc3R1dnd4eXoxMjM0NTY4OTA=”

Save this full header for later use.

Now you should have:

  • Client ID
  • Client Secret
  • Redirect URI
  • (Optional) Additional Redirect URIs
  • A base64 encoded header

Obtaining a Refresh Token

Preparing your POST call

A step in this part of the configuration has a 2 minute window, be prepared to make a POST call.

First you will need to get ready to make a POST call using Postman or your preferred application to https://api.vault.netvoyage.com/v1/OAuth with the headers:

  • Authorization: The client's encoded header token (e.g., "Basic ABCDE1234...")
  • Accept: application/json

and a body of:

  • grant_type: authroization_code
  • code: the code returned by the client (obtained in the steps below)
  • redirect_uri: the client's redirect URI

Before you send this POST you must first get the code from the client. The code has a two minute validity window so be sure to have your POST call ready to go.

Getting the Authorization Code

Before continuing be sure to have https://www.urldecoder.org/open in another tab. You will need to decode the authorization code as soon as you receive it from the client. Additionally, you will need to have https://www.urlencoder.org/ open in another tab to encode the refresh token.

To get the encoded authorization code from the client send them this URL, formatted with the client's information:

https://vault.netvoyage.com/neWeb2/OAuth.aspx?client_id=<CLIENT_ID>&scope=lookup%20read%20edit&response_type=code&redirect_uri=<REDIRECT_URI>

Notice three things here:

  1. client_id = The client ID obtained from NetDocuments
  2. scope = You must pass the scopes: lookup, read, and edit. All available scopes are as follows:
    • read:  read all data the user has rights to access
    • edit: upload document content, create versions, check out, check in, change official version, create or modify document attachments
    • organize: create folders and saved searches, file items in folders, manipulate ACLs and profile values, manipulate favorite lists, home page, and recent docs lists, change folder parent
    • lookup: insert, update, and delete lookup table rows
    • delete doc: delete documents
    • delete container: delete folders, saved searches, filters, and workspaces
    • full: full access to all resources.  The application is permitted to do everything the user has rights to do.
    • admin: needed for repository user list and group list along with the read permission.

If more than one scope is desired connect them with a space (e.g., scope=read edit)

  1. redirect_uri = The client's redirect URI obtained from NetDocuments

Once the client has entered the URL in their browser they will be prompted to Allow or Deny the token grant. When the client accepts they will be redirected to a new URL similar to this:

https://www.example.com/app/?code=abcdefghijklmnop

Take the contents of the url entry after 'code=' (i.e., abcedef...) and decode the value using https://www.urldecoder.org/ .

Now take this decoded value and place it into the body of your POST call.

If you receive a message with "error": "Invalid grant" you might have passed the 2 minute validity window of the authorization code. Try again with another code from the client.

Now you'll receive a response that has:

  1. Access Token
  2. Refresh Token
  3. Token Type (Bearer)

Once you receive the refresh token do not make the POST call again or you will invalidate the token.

In https://www.urlencoder.org/, ENCODE the refresh token.

Place these 3 items in the appropriate sites in the Get Token Rest Request Action in Onit:

  1. An encoded client id and client secret (e.g., Basic ABCDEF123...)
  2. An encoded refresh token 

Finally, you have a 20 minute window to run the Get Token Action and replace the hardcoded refresh token. All subsequent token calls will refresh this token (it expires in 60 days if unused).

Previous Article Onit Outlook Email Plug-in Configuration
Next Article Using Badges to Enhance App Orchestration Visibility and Workflow

© 2020 Onit, Inc.

docs.onit.com contains proprietary and confidential information owned by Onit, Inc. that is subject to copyright. Onit presents it exclusively to you for your sole use in conjunction with using Onit products. No portion of the materials contained herein may be used for any other purpose. No portion of the materials contained herein may be shared with third parties or reproduced in any form.