This document contains an outline of what is needed to set up the iManage Actions that create and maintain a workspace from Onit to iManage. This procedure will require you to work directly with the client's iManage consultant, as there are Field names and values that are brought over from iManage that you will not have access to inside of Onit.
There are a couple of things you should take note of before you begin configuring you iManage instance.
First, the iManage integration is compatible with iManage release version 10 or higher.
For the Workspace iFrame feature to work as expected, you will need iManage release version 10.1 or higher.
The integration is not guaranteed to work with iManage release versions before version 10.
Second, we recommend that the integrated solution include only one iManage client instance.
The solution can be configured to incorporate multiple instances by creating different Workspace Actions.
However, you should be aware that it increases complexity in configuration and could be difficult to troubleshoot later on.
Finally, in order to create an accurate mapping to the fields in iManage, you will need to work with your iManage consultant to determine which fields should be brought into the iManage List Provider.
We recommend that you work with their iManage representative to obtain/clarify the specific Onit/iManage Field mappings in a single Excel spreadsheet.
One tab should contain the Onit Field to iManage Field # mappings (see Fig. 1), a second tab should contain the metadata and security mappings (see Fig. 2).
Figure 1 - Onit Field to iManage Field # Mapping. Note that the iManage Field # is the same as Profile Field, and is often listed as "CUSTOM9"
Figure 2 - Metadata and Security Mapping Requirements
Now that we have the background we need to get things set up, let's get going!
Setting up the Authorization Provider
First, you will need to configure the Authorization Provider for iManage. You will need to switch to the app's /better_advanced_designer page and select Auth Providers, click on the “+” to create a new iManage Login. In order to set this up, you will need:
- The specific iManage Base URL
- The User Name
- The Password
These should already have been provided to you, if they have not, please contact your iManage consultant.
This iManage Login is created in order to provide the app with direct access into the iManage environment. Once the connection is made, you will have direct access to field values in iManage during the next step.
If you had more than one iManage instance to connect to, you would need to repeat the steps above until all instances were connected.
Note: The Auth Provider only allows for direct connection to the iManage instance. There is no way to handle multiple layers of connection security.
Setting up the iManage List Provider
The next step is to configure iManage List Providers in Advanced Designer. We navigate back to the Advanced Designer page for the app and choose List Providers from the lefthand sidebar (Figure 3).
Figure 3 - Selecting the iManage List Provider
There are 3 different types of iManage Lists that can be set up:
- The Workspace List Provider is used to point to an existing iManage Workspace (Figure 4).
- This is the most important List Provider and the one that will require you to work with your iManage consultant to determine which fields to bring over. The "Anything" option will return every value, or if this is recorded in a unique field in iManage, you can point to just that field.
- The specified fields in the Columns property will determine the attributes on which the existing Workspaces are filtered.
- The Templates List Provider allows you to point to existing templates that have been set up in the iManage Workspace from a Field in Onit. This lets you create the proper layout in iManage when you create a record in Onit.
- The Category List Provider allows you to point to existing categories in the iManage workspace
Figure 4 - Selecting an iManage List Provider
Setting up the App
Once you have set up the Auth Provider and the List Provider, it is time to set up the app where we would like iManage.
To do so, we will add the following Fields to the Builder:
|Field Name||Field Type||List||Search column||Value column||Filter column||Filter by||Hidden Condition?||Calculation?||Calculation Value|
|template_id||Listcombo||iManage Template Provider||id||id||id||template_id||No||No, but you could make this a text field and create a calculation based on other field values||N/A|
- This must be an HTMLfield
- This can either be a Combo Field or Liquid calculated
- This is a Combo Field
All of the fields in the above table are required as they declare which new/existing workspace the data in Onit should be pushed to.
Creating the Workspace
Next, you will need to create a Create iManage Workspace Action. The Create iManage Workspace Action is needed to execute the creation of the workspace in iManage from within Onit. This Action can eventually be associated to an Action Button or a Business Rule that pushes the data from Onit into the dedicated iManage workspace.
This Action directly maps the relationship between Onit Fields and iManage Metadata fields. This mapping has to be gathered from your iManage consultant, who is the only person who knows the field names for the iManage environment. You will not have direct access in Onit to these values in order to do the work yourself.
The specific iManage fields being pictured below are examples - everyone will have different fields that they will want to be transferred to their iManage environment (Figure 5).
Figure 5 - Creating the iManage Create Workspace Action
As you can see, there is a lot involved in setting up this Action, so we'll go through it a step at a time:
- For the iManage Auth Provider property, make sure you select the correct Auth Provider.
- This is especially important if you have more than one iManage instance being configured, however, more than likely there is only one to choose from.
- For the Template ID property, you can use Liquid to pass in the value from your template_id Field
- For the Workspace ID property, select the Display Name for the Field workspace_id.
- For the Workspace name property, use Liquid to create custom name. In our above example, we pass the name of the transaction
- For the Workspace Description property, you can use Liquid to create a custom name. Here we have used the matter description
- Owner, Owner Description, and Category are all optional properties that can be sent. In our above example we have left them blank
- One of the most important properties is the Workspace URL. This can be attained by logging in to the client's iManage environment and taking everything from after the .com up until the workspace ID near the end.
- For the Link To Workspace field property, select the Display Name for the Field workspace_link_id.
- For the Workspace Access property, you can either hardcode in a value from the listed options, or you can make this a Combo Field for the end user to select
These are the main options for configuring the Action, however nothing we have done so far besides sending in the name and description of the transaction has pushed any data into iManage.
This is where the Validated Lookup Fields and the Custom Fields options come in. Here, you can add preconfigured fields in iManage that match to your Fields in the Onit transaction using the Validated Lookup Fields. Or, you can push Onit data into custom-created fields in iManage using the Custom Field.
There are a couple of things to note about these fields.
For one, think of a Validated Lookup Field as one field made up of two sub-fields, Alias and Description. When creating a custom mapping using the Validated Lookup Field, select a specific iManage field and then point each sub-fields to the correct Onit Fields. These two Onit Fields will provide iManage with both the Alias and Description values.
On the other hand, Custom Fields are not made up of sub-fields. A Custom Field will map to a single Field in Onit.
There is one big Note here - The Create iManage Workspace Action performs an upsert against the iManage environment. This means that if your data needs a refresh in iManage, you can re-use this Action wherever necessary to send the data back to iManage
Note: There are many custom fields that you can select from, however iManage may require re-indexing if you change a field type, and some fields may be required by the iManage instance. If you need information about which fields can be truly custom and which to avoid, talk to your iManage consultant.
Adding Participants to an iManage Workspace
Figure 6 - Add Participants to Workspace Action
The next iManage Action to configure is the Add Participants to Workspace Action (Figure 6). This Action will map Users from Onit into pre-defined roles in iManage. These Roles must match between the two environments.
In order to set up the Action, select the correct Authorization Provider and the workspace_id Field.
Then click the Add button to configure as many Participant types as you would like.
For the Type property, there are two options:
Groups are particularly helpful if you need to add a specific User Group from Onit to the Workspace.
For the Access Type property, you have four options:
- Read Write
- No Access
These correspond to iManage-specific security permissions. You should be able to get a list of what permissions each user or group should have from your iManage consultant.
The Participant property, though marked as required, is not - it can be left blank. However, you can use Liquid to select which User/Group you would like to add. In our example above, we are using the requester_name to set up a User in the Workspace.
Once you have set this up, you can bundle it into a Conditional Compound Action to be used in conjunction with the Create iManage Workspace Action, or you can tie it to its own Button.
Removing Participants from an iManage Workspace
Figure 7 - Remove Participants from Workspace Action
The Remove iManage Participants Action also does exactly what it sounds like - removes Users from the Workspace (Figure 7).
In order to set up the Action, select the correct Authorization Provider and the workspace_id Field.
Here, instead of selecting User or Group from a dropdown and then using Liquid to define who should be removed, instead you have the option to either use Liquid to set an Email to be removed, or to define a Group.
Setting Up an iFrame Panel
In addition to being able to create a Workspace, there is also the ability to let users access and view information in that Workspace directly from the Onit transaction through the use of an iFrame. As noted earlier, this will only work if you are using iManage version 10.1 or higher.
Please note that there are several significant Gotchas surrounding the iManage iFrame, and you ignore these at your own peril. Without the proper setup of these items, the iFrame will refuse to load at all.
- An Onit-specific YAML config file must be installed on your iManage Work Server and configured for each environment.
- For the iframe to authenticate into iManage correctly, a redirect URL must be provided to your iManage consultant so that the URL can be included in a YAML configuration file that is set up on your iManage server.
- The redirect URL should be the URL for the Onit domain where the iManage integration is configured. This means, this will change from Dev to UAT to Production for each any client implementation of the iManage integration.
- The format of the redirect url will be the onit domain url, with the following appended: /imanage/authorized
- For example: https://[your domain name].onit.com/imanage/authorized
Once you have set up the YAML config file on your iManage Work Server and properly managed the redirect URL, you can begin to build the iFrame.
You can find the iFrame option on the Advanced Designer page under the App Panels sidebar item. When you click 'Add', it will appear as a dropdown option as shown below in Figure 8:
Figure 8 - Selecting the iManage iFrame Panel
Here you are greeted with multiple properties to enter. You can name the panel whatever you wish, but the following properties are required for the iFrame to work:
- API Key
- API Secret
- Workspace ID Field
For the URL, you will need the Base URL to your iManage instance that you used when you created the Auth Provider
The API Key and API Secret will need to be obtained from the iManage team directly, and this will require either your iManage expert or direct communication with the iManage team. The API Key and API Secret will also be in the YAML config file you created earlier. If you are not sure what these values are, you can request them directly from your Onit contact.
The Workspace ID Field property should point directly to the Onit Field where the workspace_id is captured. It should be listed in the dropdown menu.
The Height property will default to the standard 500 pixels, but depending on the information input into the app in question, you might need to make it taller than that.
Once the iFrame has been set up, it should appear in any record where an iManage Workspace has been created. It will appear as its own tab on the main panel of the transaction. Clicking on the tab should launch the iFrame directly in the transaction, and the end user will be able to use iFrame from within the Onit environment.
And that's it! You have configure an iManage integration that will allow you to create usable workspaces where you can push the latest updates from your Onit app into them, drag and drop documents from your desktop right into iManage folders, and even red-line documents, right on the same screen as all of the rest of your helpful Onit information!