User Guide – imDocShare app for SharePoint Server 2013

This guide is a general overview of how to use and configure the imDocShare Visual Web Parts designed for SharePoint 2013 on-Prem. We offer two different solutions: A Farm solution and a Sandbox solution. The functionality between these two different types should be the same for most cases, however, we list the major differences in a following section entitled “Farm vs Sandbox Differences”.

If you would like to use imDocShare WebParts for SharePoint Online, or on-Prem 2016 and later, we provide a different SPFx (SharePoint Framework) based solution that has the correct compatibilities to support newer environments.

imDocShare WebParts can be configured and customized in several ways to show the most appropriate documents and containers for a respective user or situation. These Web Parts include *:

  1. imDocShare Document Viewer
    • JSON Config Builder
    • Normal View
    • RecentDocs View
    • Favorites View
  2. imDocShare Tree View

This is not a guide for deploying the Visual WebParts solution to SharePoint. This documentation assumes that an Admin user has already deployed the solution in the Site Collection’s Site Settings. If you need help with initial deployment, please see our documentation entitled “imDocShare – Visual WebParts Deployment Guide for SP2013 on Prem”.

Note: Site Collection Libraries MUST be able to host JSON and js files or else deployment will fail. Any security measures that block Popups or iFrames must be turned off as our authentication uses these resources.

Supported Browsers:

  • Microsoft Edge
  • Google Chrome (latest released version)
  • Mozilla Firefox (latest released version plus immediate previous version)
  • Apple Safari (latest released version)
  • Internet Explorer 11 (limited support only. IE11 Protected Mode is not supported)

Not Supported Browsers:

  • Internet Explorer 10
  • Internet Explorer 9
  • Internet Explorer 8
  • Internet Explorer 7
  • Internet Explorer 6

imDocShare comes with a unique license ID which will be verified on load. Please note that imDocShare requires an internet connection to verify your license, which should not be an issue since it also requires internet to retrieve content from the IManage API.

When receiving our imDocShare deployment materials, you should also have received a imDocShareLicenseKey.txt file. This file contains your unique key which will activate imDocShare and the specific features that you have requested. In order to activate, simply drop the key file, which we have provided, into the library where our assets were deployed. Neglecting this step will yield licensing errors and will not allow usage of the app. In our farm solution, the assets will deploy to a location on the file system. We have given an example path below:

AssetPath:

https://{your-SharePoint-Tenant}/_layouts/15/imDocShareFarm/assets/images/folderIcons/

File Path:

C:\Program Files\Common Files\Microsoft Shared\Web Server Extensions\15\TEMPLATE\LAYOUTS\imDocShareFarm\assets\images\folderIcons

Attempting to use the app without putting in the license key will be able to yield the exact path in an error message similar to the one shown below:

All the WebParts included in this project have a few global features that are common among components regardless of which view you are using:

iManage REST API service:

The WebParts feature automatic authentication once a user has logged in once, in the same browser. This state will last for the length of your token expiration, which can be set in your application settings on iManage. Authenticated users can query any documents or source locations that they have permission to access on iManage. Users are also able to execute actions that make changes to the documents, such as add/remove favorite or Uploading a new document to a location.

Search:

All WebParts feature a search bar in the top right corner, that can be used to search through the content from the document sources. More about this feature can be found in the section on Search.

Favorites:

Documents and containers can be set as favorite. Favorited documents and containers will be displayed in the “Favorites” view.

Configurable table view:

All components have configurable table columns which you can include in the initial AppConfig Object. Column data is based on the standard and custom fields that exist on each iManage entity. These attributes are listed further below.

If you omit the values for ``columnProperties``, our webpart will use the default properties: version, id, extension and modified date. This can be changed by editing the JSON manually or picking the values from the corresponding dropdown menus in the config Builder.

If you omit the values for ``contextMenu``, our webpart will select all available menu options by default. This can be changed by editing the JSON manually or picking the values from the corresponding dropdown menus in the config Builder.

Sorting:

Documents can be sorted and reverse-sorted by clicking or double-clicking on the column property-title by which you want to sort.

View Document:

All documents displayed in a WebPart, upon click, will (by default) open the document’s preview page which is powered by iManage. This default click behavior is customizable using your config options. Please see our section on config options to customize this behavior. There are a few different behaviors that users can select:

Open iManage preview (default):

Clicking on any document will open the document in the iManage preview window

Open in iManage (default):

Clicking on any document will open the document’s page in the iManage.com website

Download:

This option will simply download the selected document on click

Search is a global feature that exists on every WebPartt. Search functionality will vary depending on the type of content that is retrieved by the WebPart. There are 2 main ways that the search bar can be used: as a filter that filters all on-screen content or as an API search that sends a query to the iManage API for further information.

In cases where prominent subfolders exist, such as in workspaces with subfolders or in TreeView where there are multiple sources, the user will see a search button denoted by the standard magnifying glass icon.

When the user clicks the search button or presses enter with a search term, the WebPart will execute a query to iManage that searches through all containers and sub-containers that are contained within the primary container which contains the source location used. The current contents of the display table will then be replaced by the search results. Users can revert to the previous view by pressing the “x” button inside the search box.

Note: When using any type of search for on-Premises clients, please ensure that your iManage work server installation includes some type of indexer service. Typically, iManage provides a few different choices and this can be configured with the same installation materials used to install the iManage work server. Without an indexing service, any API search call will not return expected results. This can be mitigated by using wildcards on some specific field queries but overall search will be crippled without the indexer.

User can select the ‘filter icon’ to filter column data based on the current data being displayed in the table. Enter a filter query into any of the column fields and the view will update with current data that matches the query.

A user can end the filtering by either clicking the ‘x’ in the field where a filter query was entered, or by re-clicking the ‘filter icon.’

Users can upload a new document into any WebPart which has a specific source location that is a container. For example: folders and workspaces are valid containers that one can upload to. Whereas, views such as RecentDocs or Favorites or Saved Search View are not valid containers and therefore cannot be uploaded to.

Simply click the upload button and it will open an upload dialog window. In this window, users can choose a file from their local machine to upload.

In TreeView, there are usually multiple sources displayed. In this case, the upload destination will be the latest cabinet/folder/sub-folder selected by the user.

The uploaded documents will immediately be sent to your iManage repository barring any error happening. Users will be notified of any errors during upload. Please note that, even after successful upload, in some limited cases, the user’s view on imDocShare may not immediately update to show the newest upload. This is due to the fact that iManage processes and indexes the files in the background and the indexing priority tends to be lower for API uploads. This can be avoided by waiting a few minutes and refreshing the WebPart.

The imDocShare JSON Config Builder is one of our essential webparts when working with imDocShare for the first time. This is because of two major reasons:

The JSON builder is the only webpart that does not require authentication. This means that it can be used to test whether the app is loading or not, without the complications of authorizing and authenticating with IManage.

The JSON builder can be used to help create configs for all the other webparts

Note: More information about the JSON builder could be found in “How to use SP JSON Builder”

Create a new page or use an existing page configured with the JSON builder webpart. Too add the webpart, go to the top ribbon and select Insert > Web Part. For Sharepoint 2013, you can use the WebPart named “DocumentViewer” to load the JSON Builder.

Note: Make sure that the page created for the webpart is specifically a “webpart page” instead of “wiki page,” which is the default option. Clicking “new” to create a new page will default to wiki page

After selecting the correct webpart, click the edit button and use the right panel side panel to enter your configs. Create the JSON Builder webpart by pasting the following in the webpart config window:

{ “viewType”: “createConfig”,

“assetPath”: “{your asset path here}” }

Your assetPath determines where the webpart will load its code and assets from. Typically, this can be found during the deploy process. Here is an example of a typical path we usually see in Sharepoint 2013 On-Prem:

https://{your-Sharepoint-Tenant}/SiteAssets/imDocShare/CDN/assets/images/folderIcons/

After your .WSP solution file has been deployed, you can also navigate to this library to check that your assets have been deployed correctly.

Once you have inserted the config and clicked “OK” the webpart should load and you will see something similar to the following:

Now you can use this form to create proper configs for the other Webparts. More information about how to use this tool can be found in the section entitled “How to use SP JSON Builder.”

imDocShare absolutely requires authentication with the iManage API service before any content can be returned to the user. This is a very important security step that cannot be bypassed. Only valid iManage account holders can see content from iManage through our application. Our application can use 3 different types of authentication for 3 different purposes:

  • Standard OAuth with username and password screen from iManage (used for typical logins with a login screen)
  • SAML Authentication (used when Single-Sign-On is enabled on the client environment)
  • Password Grant OAuth with preset username and password (used for impersonation or custom login screen)

All of the above types of authentication use access and refresh tokens to persist the API session. The expiry values and other behaviors of these tokens can be customized and configured in your Application screen in the iManage Control Center.

Standard OAuth

Standard OAuth will present users with a typical login screen which comes straight from iManage itself.

Filling in the login screen will send a signal to the iManage servers which will validate your credentials and send back tokens which you can use to access the API. Token management is done using a KLST-hosted service app which will return tokens to you based on the redirect URL.

SAML Authentication

SAML authentication will only work if the client has the infrastructure set up to enable Single-Sign On with their identity provider. For example, Azure Active Directory services is typically used to tie the user’s Microsoft credentials to their iManage account. If your environment logs in automatically when visiting iManage on the web, SSO may already be enabled. Once this is set up, imDocShare will automatically leverage the same SSO system to login to iManage. A login popup will still appear for a split second but it should resolve on its own.

Password Grant OAuth

Password Grant OAuth is used in limited cases when impersonation needs to be used, such as impersonating an admin level service account or using a custom login screen in the case of iManage work web not being available.

To use Password Grant OAuth, please choose “custom Login” or impersonation in our config builder’s login options. Choosing the impersonation option will open up the username and password fields immediately, please enter your credentials here to activate automatic & impersonated login. Choosing the custom login option will replace the iManage login screen with our own login popup which will ask for username and password. All password fields in imDocShare are encrypted upon entry.

Tokens & Lifetimes

Access tokens have a limited lifespan. They expire after 60 minutes of no activity or between 24 and 48 hours of when they are issued. If an API is made with an expired token, a 401 Unauthorized status is returned. imDocShare automatically processes expired tokens and attempts to retrieve a new token when required. For this, we use refresh tokens which last much longer.

With the new OAuth implementation, the refresh token with full access will expire in 40 days rather than 1 year. A refresh token with the least access will expire after 90 days. Once the refresh token has been depleted, users will be expected to enter their login credentials again in order to obtain a new refresh token.

This is different from a login lifetime when using IManage itself. IManage for security reasons will log out users automatically after 90 minutes of inactivity. As a IManage user, you can enable an automated login option if your organization has Microsoft Active Directory Services.

Logout

Logging out from iManage can be done on a browser level. For example, if you log in to iManage.com in a browser tab and open a SharePoint page with imDocShare webparts in another tab, it will recognize that you are logged in and automatically retrieve tokens.

We also provide an optional method to log out from inside ImDocShare. The Config Builder contains a field called “Show Logout”. When enabled, this will include a dropdown menu on the top right side of the webpart which will display a greeting and the iManage user’s name:

Clicking on this will reveal a logout option which will remove the iManage session from the browser. Note: This will log you out of iManage in every tab of the current browser. The page will refresh automatically, and users must login to iManage before resuming usage.

In normal view, it can show a single workspace: a collection of related folders and documents. It can also show individual containers such as a single folder.

In Tree view, it can show multiple containers, including workspaces and folders, side-by-side. This allows the user to view containers and files from different chosen sources in the same viewer.

In RecentDoc view, it can show the user’s most recently accessed, opened or added documents.

In Favorites view, it can show user-specified favorite documents or folders

With JSON Config Builder, users can create config objects used to configure all other webparts

Let’s add the Document Viewer, our first real WebPart after Auth. You can add the Document Viewer WebPart by picking it in the same menu where you added the Auth WebPart from. Similar to auth, it will require the user to insert a configuration object before it can start up. An example and explanation of the DocumentViewer JSON Config Object is shown below:

Viewtype: Normal View

{

viewType“: “normalView”,

primarySource“: { “id”: “ACTIVE!78”, “type”: “folder” },

baseURL“: “https://cloudimanage.com”,

columns“: [“name”, “version”, “id”, “edit_date”, “type”],

contextMenu“: [“download”, “delete”, “rename”, “favorites”, “checkOutIn”, “prevTab”, “prevBrowser”, “coauthoring”],

docsPerPage“: “50”,

libraryId“: “Active”,

showBreadcrumb“: true,

showLogo“: true,

showSearchBox“: true,

showLogout“: true,

searchBehavior”: “searchContainer”,

assetPath“: “https://{yourSharepointTenant}/sites/AppCatalog/ClientSideAssets/

}

For explanations of each property, what they do and what values should be used to change them, please see our Config Builder Properties Appendix at the end of the document.

Viewtype: Recent Doc

The Recent Doc viewtype is a different configuration of the Document Viewer Webpart that shows a collection of recent documents or workspaces that are derived from the individual user account of the iManage user. The only difference between a regular document viewer and RecentDocs lies in the configuration. RecentDoc has the simplest configuration as it does not require any sources or additional configuration. It simply shows the last 40 most recent documents based on the user’s account. This list will only be updated after edited documents have been checked in, or after they have been initially uploaded.

An example and explanation of theRecent Doc JSON Object is as follows:

{

viewType“: “normalView”,

primarySource“: “recent”,

baseURL“: “https://cloudimanage.com”,

columns“: [“name”, “version”, “id”, “edit_date”, “type”],

contextMenu“: [“download”, “delete”, “rename”, “favorites”, “checkOutIn”, “prevTab”, “prevBrowser”, “coauthoring”],

docsPerPage“: “50”,

libraryId“: “Active”,

showLogo“: true,

showSearchBox“: true,

showLogout“: true,

searchBehavior”: “searchContainer”,

assetPath“: “https://{yourSharepointTenant}/sites/AppCatalog/ClientSideAssets/

}

For explanations of each property, what they do and what values should be used to change them, please see our Config Builder Properties Appendix at the end of the document.

Viewtype: Favorites

The Favorites viewtype is a different configuration of the Document Viewer Webpart that shows a collection of user-defined favorites that are derived from the account of the iManage user. The only difference between a regular document viewer and the Favorites view lies in the configuration and the configs for favorites is identical to Recent Docs except for the primary Source.

An example and explanation of the Favorites JSON Object is as follows:

{

viewType“: “normalView”,

primarySource“: “favorites”,

baseURL“: “https://cloudimanage.com”,

columns“: [“name”, “version”, “id”, “edit_date”, “type”],

contextMenu“: [“download”, “delete”, “rename”, “favorites”, “checkOutIn”, “prevTab”, “prevBrowser”, “coauthoring”],

libraryId“: “Active”,

docsPerPage“: “50”,

showLogo“: true,

showSearchBox“: true,

showLogout“: true,

searchBehavior”: “searchContainer”,

assetPath“: “https://{yourSharepointTenant}/sites/AppCatalog/ClientSideAssets/

}

For explanations of each property, what they do and what values should be used to change them, please see our Config Builder Properties Appendix at the end of the document.

Viewtype: TreeView

The Tree View WebPart shows a collection of container objects (folders and workspaces) on the left pane, with a corresponding document-viewer pane on the right. Subcontainer objects will unravel and be reveal in a tree-like structure on the left pane as the user clicks deeper into the directory. In this view, all containers will appear on the left side pane and only documents will appear on the right-side pane.

Installation instructions:

Much like the set-up process for Document Viewer and Recent Doc WebParts, you will add the imDocShare TreeView WebPart from the imDocShare WebParts group under the Categories gallery and configure its settings by entering an App Configuration JSON Object inside the Config Settings field, and then clicking Apply. An example and explanation of this TreeView JSON Object is as follows:

{

viewType“: “treeView”,

primarySource“:[{“id”:”ACTIVE!148″,”type”:”folder”},{“id”:”ACTIVE!150″,”type”:”folder”},{“id”:”Active!143″,”type”:”folder”},{“id”:”Active!187″,”type”:”folder”}],

baseURL“: “https://cloudimanage.com”,

columns“: [“name”, “version”, “id”, “edit_date”, “type”],

contextMenu“: [“download”, “delete”, “rename”, “favorites”, “checkOutIn”, “prevTab”, “prevBrowser”, “coauthoring”],

docsPerPage“: “50”,

libraryId“: “Active”,

showLogo“: true,

showSearchBox“: true,

showLogout“: true,

searchBehavior”: “searchContainer”,

assetPath“: “https://{yourSharepointTenant}/sites/AppCatalog/ClientSideAssets/

}

For explanations of each property, what they do and what values should be used to change them, please see our Config Builder Properties Appendix at the end of the document.

ImDocShare also supports the insertion of custom column properties. In order to use custom properties, please visit your IManage tenant control center page, navigate to Custom Fields on the left hand side, where you will see the current list of created Custom Fields and their labels ‘captions’.

Note: If you are creating a brand-new custom field, it may take some time for the data to populate properly. Please wait a few minutes after creating the custom field for the data to be correctly associated in the iManage API.

In the figure below, you can see the custom column “Client” has been implemented.

If the JSON builder has not been created yet, the following steps will create one.

Create a new page or use existing JSON builder webpart. Adding the JSON builder is a good test to determine if the app has been deployed correctly because it is the only view which does not require authentication with IManage.

After generating the imDocShare webpart, click edit button and wait till right panel shows up. Create JSON Builder webpart by pasting

{ “viewType”: “createConfig”,

“assetPath”: “your asset path here” } to the imDocShare webpart.

Note: Make sure the assetPath example includes the correct path (replace yourSharepointTenant):

https://{yourSharepointTenant}/SiteAssets/imDocShare/CDN/assets/images/folderIcons/

(Optional) To modify an already existing config string, click the Import button on bottom left.

Copy and paste the JSON string. Then click Import. This process will populate the form with provided data.

Choose options that you would like to show on Webparts.

The possible options include:

View Type:

Normal View, Recent Documents, Favorite Documents, Tree View

Documents per page:

The number of documents loaded during the page-based scrolling. The minimum is 1, and the maximum is 50. This does NOT affect the amount of results initially loaded. This is determined by the type of container and its contents.

Show Logo:

An option to show or hide the large logo in the upper left-hand side of the screen.

Show Logout:

An option to show or hide the option to Logout from the signed-in   iManage account.

Show Search Box:

An option to be able to search through documents.

Search Behavior:

Search Container searches the currently viewed container, and all the sub-containers and files within that container for their metadata (Name, ID, Custom Field). Search All searches the entire container listed in the web-part regardless of the current view position,  and all the sub-containers and files within that container for their metadata (Name, ID, Custom Field) and a search within the content of those files.

Show Breadcrumb (Normal View Only):

Choose to display the container path of the currently displayed container in the view

Show Parent Container (Tree View Only):

Choose to display the name of a container’s parent container in the tree-nav panel

Source Name:

The name of the container, obtained in iManage.com* or from our dropdown list on the Webpart.

Source type:

Type of container. This can be a folder or a workspace

Column Properties:

The desired columns displayed on the web part.

Context Menu:

What options are available in the dropdown context menu for each file.

Asset Path:

The URL where the assets and license key are stored for your application

*Note: For Tree-View webpart creation, please don’t forget to press the “ + ” button next to fields such as Source Name or else the form will not register the input.

The ID of workspaces and / or Folders can be found by inspecting the following

Config builder also features automatic source querying when the user is logged into iManage. Your main library will already be chosen, once you have chosen a viewtype and source type, you will be able to see a dropdown of a selection of sources that match your parameters. If your source is not in this list, you can also search for it by name or ID.

After setting your desired configuration, click ‘JSON View’ or ‘Copy to Clipboard’ button to copy the JSON string.

If deciding to modify an existing page, then click on “edit” button, and click on the IManageViewer webpart. After right panel pops up, replace the config that was generated using Config Builder into IManageViewer web part.

Click ‘Publish’ to publish the page.

Step-By-step instructions for how to update an existing Web Part:

  1. Navigate to the page in which you wish to edit the imDocShare Document Viewer Web Part. In the example below, we are selecting a “Test” page.
  2. Click Edit Page in the upper right-hand corner.
  3. Click the Web Part menu (small arrow in the upper right-hand corner) and then select Edit Web Part.
  4. Select Extended Settings at the bottom, click inside the Config Settings field and paste the App-Configuration JSON Object directly. Then click apply and then Ok.

ImDocShare uses a JSON-formatted config object to customize views and webparts to suit a user’s needs. Below you will find a list of properties and their possible values. All properties should be editable in a more user-friendly fashion by using the SharePoint Config Builder webpart, however, more technical users can also edit these properties manually in the JSON.

Base Properties

Base properties are fundamental requirements of each webpart. They often set baseline properties that are required for the webpart to work in the first place.

  • viewType is the property that tells SharePoint which imDocShare WebPart to load. The available values are: ‘normalView’, ‘treeView, ‘createConfig’.
  • assetPath is the full path where static assets are stored and must be obtained during deploy. This config is mandatory as it is also used to determine licensing information.

If you are in SharePoint online (currently included in the config above) your asset path may look like the following:

https://{yourSharepointTenant}/sites/AppCatalog/ClientSideAssets/23dea53d-fbee-49c3-8b16-c6b586b0422f/

If you are on Share Point on Prem Your asset Path might look like the following:

https://{yourSharepointTenant}/SiteAssets/imDocShare/CDN/assets/images/folderIcons/

Source Properties

Normal View can be configured to show a specific source container. TreeView can be configured to show several source containers. The ‘primarySource’ and ‘sources’ properties are used to control this.

  • primarySource is the container object that you would like DocumentViewer to display. primarySource is always required, even if using a source that does not have an explicit source ID such as Recent Documents. primarySource can be a folder, workspace, Category, Search folder. In the case of a workspace, primarySource can look like
    • “primarySource”: {“id”: “ 4112-9032-1392“, “type”: “workspace”}
  • sources are always required in TreeView. sources should be an array of key-value pairs, where “id” is the id of the folder, and “type” should tell whether the object is a folder or workspace:
    • “primarySource”:[{“id”:”ACTIVE!148″,”type”:”folder”},{“id”:”ACTIVE!150″,”type”:”folder”},{“id”:”Active!143″,”type”:”folder”},{“id”:”Active!187″,”type”:”folder”}],

Display Properties

columnProperties are a collection of iManage properties by which you would like to see and sort you’re the metadata of your content. The Document Viewer WebPart displays “name” as the first default document property to display, and in this example, “Ext“, “id“, “createdBy“, “modified” are the next four customizable document properties to display. ‘Ext’ or extension translates to “Document type,” “DocId” to “Document Id,” “createdBy” to “Pillsbury author,” and “modified” to “Date modified” as seen below:

If you omit the values for ``columnProperties``, our webpart will use the default properties: id, extension, createdBy and modified. This can be changed by editing the JSON manually or picking the values from the corresponding dropdown menus in the config Builder.

ImDocShare also supports the insertion of custom column properties. In order to use custom properties, please visit your IManage control center, and make sure that the custom fields properties are enabled, then edit the Custom Field property on the desired container or file on your iManage tenant, and the property value will appear on your ImDocShare webpart.

Note: If you are creating a brand new column, it may take some time for the data to populate properly. Please wait a few minutes after creating the Profile Attribute for the data to be correctly associated in the iManage API.

In the figure below, you can see the custom column “Client” has been implemented.

  • contextMenu determines what options will appear in the dropdown context menu that is opened from clicking the “…” button beside each document. The contextMenu can be disabled by completely removing the key and value from the config object. Users can add other options indicated in the list below:

“download”,”delete”,”rename”,”favorites”,”checkOutIn”,”prevTab”,”prevBrowser”

If you omit the values for “contextMenu”, our webpart will select the default options. This can be changed by editing the JSON manually or picking the values from the corresponding dropdown menus in the config Builder. Please see an example of the context menu with all options turned on below:

Optional Display Properties

  • showLogout is a property which control whether or not the welcome message on the top right appears. This message can be clicked to reveal a small dropdown containing the ‘logout’ option. The default value is false, Omitting this value will set the value to false.
    Note: On the Microsoft Teams implementation of our app, logout is required on every page, therefore this property is set to true and will not be editable by users
  • showLogo is to show or hide the imDocShare logo image at the top left. Note: Image can be customized by replacing the file in the static images library.

Example: “showLogo” : true, //Accepts Boolean

  • For Normalview: showBreadCrumb is a property which hides or shows the bread crumb trail. A Breadcrumb trail allows you to navigate through multiple levels of nested folders.
    • Click on any part of the breadcrumb trail to go back to that location.