Onit Outlook Email Plug-in Configuration

by Christina Moore Updated Jul 09, 2020

The Onit plugin for Outlook provides users a great way to work with Onit from within Outlook. The plugin allows users to view Record data, manage Records, and perform Actions on a Record from within Outlook. The Onit App for Outlook works with Outlook 2016, Office 365, Outlook for Mac, and the browser version of Outlook at outlook.office.com.

The plugin requires setup from both within Onit and Outlook. This tutorial will start with the Onit side configuration. In broad strokes the plugin requires admins to setup a new App called Outlook Configuration. Each Record in this App represents a different configuration of the plugin. For example, users in the law group will have a different configuration than the HR group. A small amount of configuration will then be added to the User Profiles App to account for assigning default plugin configurations. Finally, we will walk through setup on the Outlook side.

Onit Side Set-up Configuration

The Outlook Configuration Onit App provides settings for the Outlook add-in, such as layout, field mappings, matching criteria, and search by fields.

  1. Create a new App named Outlook Configuration.
  2. Click on the Fields tab, then add the following Fields:
Name
Label
Type
Purpose
plugin_name
Plugin Name
Text
Unique name of plugin configuration
app_name
App Name
Text
Name of the App. The App name will be displayed in the drop-down list when multiple Apps are assigned to the user profile.
field_list
Field List
Text
Comma separated list of Fields to be fetched from the App. These fields are mapped in the row_template, search_by_fields or the incoming_email_field.
row_template
Row Template
Textarea
HTML template that will be used for rendering the rows. This uses Liquid field mapping syntax to embed fields in the template.
search_by_fields
Search by Fields
Text
Comma separated list of Field names and help text for searching Records via the plugin.
regex_filter
Regex Filter
Text
Regex expression that will be used for contextual processing to find any matching text in the email body or the subject line.
regex_field
Regex Field
Text
Name of the Field that will be used to query the API when a contextual matching value is found in the email body or the email text.
incoming_email_field
Incoming Email Field
Text
Name of the Field in the target App that provides an atom's email address. When the user clicks on the Add button for an atom, the email is sent to this address.

Designate the Transaction Provider

Next the Outlook Configuration App must be designated as a Transaction List Provider. This will allow the admin to specify a default plugin configuration for users. To create the Transaction List Provider, complete the following steps:

  1. Select the List Providers node in the Advanced Designer.
  1. Click the plus button then select Transaction List Provider.
  1. Name the list provider Outlook Configuration.
  2. In the App property choose the Outlook Configuration App you created earlier.
  3. In the Atom Columns property choose [Outlook Configuration] Project Name (Name).
  1. Click Save to save the Transaction List Provider.

Modify the User Profiles App

Note: For the Outlook plugin configuration to work, this App must be named User Profiles.

The User Profiles App must be modified to allow an admin to specify default plugin configurations. Add the following Fields to the User Profiles App.

Name
Label
Type
Comments
user_pref_plugins
User Pref Plugins
ManytoMany
Target App: Outlook Configuration
default_plugin
Default Plugin
Listcombo
List: Outlook Configuration
Search column: name
Value column: name

When configuring the user_pref_plugins Field check the Enforce App Type box.

Once the Fields are added click Save to save the App.

Create Outlook Plug-in Configurations

Before users begin using the Onit for Outlook, you can define their experience by creating an Outlook Configuration. Outlook Configurations define the plugins settings for users, such as Record layout, Field mappings, matching criteria, and search by Fields. If you’d like to define unique settings for a subset of your team, you can create multiple Outlook configurations and assign them to the user/group profile accordingly.

  1. Launch the Outlook Configuration App.
  2. Enter the Project Name of the configuration (e.g. Outlook-Matter).
  3. Enter the Plugin Name as Outlook.
  4. Enter the App Name. This should be the exact name of the App.
  5.  In the Field List property, enter the Fields you want to display in the plugin, with custom fields having the p_ prefix. Below is an example,
id, name, p_number, p_matter_description, p_matter_type, p_matter_sub_type_1, p_legal_section, p_matter_email_address 
  1. Enter the Row Template. The row template is used to render the rows on the search page (i.e., what a user will see when they search for a Record in the plugin). You can use Liquid syntax to embed fields into the template. Below is an example Row Template for the Matter App.
  1. Values in the Search By Fields property will determine what properties users can search Records by in the plugin. For each search property enter the name of the Field to be searched followed by a pipe character then the search help text. For example: p_issue|Description of Issue. Each additional search term should be separated by a comma. As always, custom Field names must be prepended with p_.

    For integer fields, you will also need to include the int type as part of the field name. This tells the add-in to use the appropriate operator for the equals query. For example, p_total_amount:int|Total Amount.

    For example, the following configuration would produce a search dropdown like the one seen in the screenshot below.

    p_issue|Description of Issue,p_ticket_number|Ticket Number,p_client|Client and Project
  1. If regex matching is desired, enter an appropriate Regex Filter into the Regex Filter Field. The Regex Filter is used to find matching text in the email body or subject line. Any valid regular expression can be specified to find text from the email body or the subject line. For example, \d{4}-\d+.

The above example will search for a 9999-9999 number pattern in the email body (7) and in the subject line (8).

  1. This property pairs with the Regex Filter property. The Regex Field property determines which Field in Onit the regex filter will be applied to. Custom named Fields should be prepended with p_.
  2. If the user chooses to associate the email with an existing Record, the Incoming Email Field is used to obtain the Record's email address. Enter the Field that contains the Record’s email address, for example, p_matter_email_address.
  3. Click Submit to save your configuration.

When users first log into the plugin from the Outlook setup wizard, these settings will take effect immediately. Any subsequent changes that you make to Outlook Configurations take effect the next time the users open Outlook.

Assign a Default Plugin Configuration in the User Profiles App

Default Outlook plugin configurations can be assigned to User Profiles.

  1. Select a User Profiles Record.
  2. Click the Plus icon on the User Pref Plugins pane to assign a default plugin configuration.
  1. Choose the appropriate plugin for the user from the popup list. Then click Relate to save your changes.
  1. Add the user as a participant to the user profile. This ensures correct functionality of the plugin.

Note: Users must participants of the Outlook Configuration Record(s) to gain access to the Outlook plug-in. Do not skip the above step.

Note: You can relate more than one Outlook Configuration to a user profile. The Outlook plugin will then display an Outlook Configurations drop-down menu so the user can choose from assigned configurations.

Configuring the Plug-in in Outlook

  1. Navigate to the Manage add-ins page in Office 365 using this link.
  2. Click the My add-ins button scroll down to Custom add-ins and select Add from a URL.
  1. Enter the following URL into the Add add-in from a URL panel replacing the subdomain with your environment’s subdomain.
    https://onit_subdomain.onit.com/office365/outlook
  2. Click Next.
  1. Click Install. Then click OK to dismiss the panel.
  1. Return to the Outlook Application.
  2. The Onit plugin should now be visible in your message pane.
  1. Click on Onit to begin using the plugin. When accessing the plugin for the first time you will be required to sign in to your Onit account. Below is an example of what a configured plugin could look like:
Previous Article Configuring an SSO Integration
Next Article Configuring a NetDocuments Integration

© 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.