Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

The Source System Integration is functionality allows CAM to integrate with any cloud-based system or system with a web service/REST API as an input to the provisioning process.

CAM supports integration with iManage, Azure AD and APIGEE-based systems, etc.

Note

A limit on the number of jobs a tenant can submit in Source System Integration now applies. The limit is 50,000 jobs. An error will warn the user on the limit, and any new Source system jobs will not be submitted for processing until the batch completes. This eliminates newer jobs continuously filling the queue or causing timeouts on the current original job.

Table of Contents

Overview

The following process describes configuring a source system

Configuring A New Source System

Open up
  1. Click on the Administration tab.

  2. Click on the Source

System
  1. Systems Configuration panel.

On
  1. Click on the actions menu on the upper

right options menu, click it,
  1. -right corner and select New Source System.

The first step shows is called 
  1. Input the basic details in the System Basic Configuration

. The following screen opens -
  1. screen that will show (see screenshot below).

    Image Modified
system

Field

Description

System Method

The type of methods use to connect the source. SOAP+XML and REST+JSON are available.

System Name

The source

system’s name.

Description

A description of the source system.

Base URL

The base url of this source system to access it.

Authentication type

The options of authentication to the source. OAuth, Username/Password, Fetch OAuth and using Oauth through Username authentication are supported.

  • Click Save System.

  • Based

    Note: Depending on the Authentication type (Fetch OAuth, OAuth), different configuration options will be displayed on

    the left side down the corner

    bottom-left of the page.

    1. Click on Save System.

    Authentication Configuration

    Expand
    titleAuthentication type OAuth

    Authentication type OAuth

    With Oauth, a set of tokens is obtained initially and then used with subsequent calls. These tokens are renewed periodically. No passwords are stored. Tokens are stored as encrypted.

    1. Auth Token Configuration, Enter the following information.

    2. and click Next

    Field

    Description

    Client ID

    This is required field. Client ID of the source system.

    Grant Type

    This is required field. The way an application gets an access token E.g. Authorization Code, Client Credentials or Password.

    Auth URL

    This is required field. Authorization URL of the source system.

    Include Client Secret in Auth Token Request?

    Yes or No. If yes, will enable Client Secret field to enter the details.

    Include Scope in Auth Token Request?

    Yes or No option. If yes, will enable Scope field to enter the restrictions to access source system.

    Base 64 encoding?

    Yes or No. If yes, all information will be encoded.

    2. App Authorization, Enter the following information and click Validate, this allows the information to be validated before saving. If there are problems with the information, the errors will display.

    Field

    Description

    Auth URL

    This is required field. Authorization URL of the source system.

    Include Client Secret in App Authorization?

    Yes or No. If yes, will enable Client Secret field to enter the details.

    Include Scope in App Authorization?

    Yes or No. If yes, scope will be included in the configuration.

    Base 64 encoding?

    Yes or No. If yes, all information will be encoded.

    1. Refresh Token Configuration and Click Save.

    Field

    Description

    Grant Type

    This is required field. The way an application gets an access token E.g. Authorization Code, Client Credentials or Password.

    Token Type

    This is required field. Select from the lookup values.

    Include Client Secret in Refresh Token Request?

    Yes or No. If yes, will enable Client Secret field to enter the details.

    Include Scope in Refresh Token Request?

    Yes or No. If yes, scope will be included in the configuration.

    Expand
    titleAuthentication type Fetch OAuth

    Authentication type Fetch OAuth

    This is a combination of application + OAuth or UserId/Password. Applications such as Office-365 support this type of authentication. In Application based authentication, the application is registered in the underlying system and pre-assigned certain permissions.

    Fetch OAuth Configuration, Enter the following information, and click Complete

    Displays the following screen:

    Field

    Description

    Auth URL

    This is required field. Authorization URL of the source system.

    Client ID

    This is required field. Client ID of the source system.

    Client Secret

    This is required field. the Client secret of the source system.

    Grant Type

    This is required field. The way an application gets an access token E.g. Authorization Code, Client Credentials or Password.

    Username

    Enter Username.

    Password

    Enter Password.

    Expand
    titleAuthentication type UserId/Password

    Authentication type UserId/Password

    When OAuth is not supported, User Id and Password are used to obtain the authentication session(token) and then session Id is passed in all subsequent calls.

    User and Password Configuration, Enter the following information and click Confirm

    Field

    Description

    User ID Field

    This is required field. User Field Name.

    User ID Value

    This is required field. User Field Value.

    User Password Field

    This is required field. Password Field name.

    User Password Value

    This is required field. Enter Password value.

    Info

    A warning will appear once an incorrect configuration is entered. It will not allow saving until the error is corrected.

    Authentication Details of External Systems

    iManage

    • iManage supports OAuth and User Id & Password-based authentication. OAuth is supported in cloudimanage.com and 10.3 versions of the private cloud (starting Q3 2020). Currently, CAM is using User & Password-based authentication. A complete OAuth based authentication will be supported by Dec 2020.

    • Permissions and Roles

      • You need to specify the NRTADMIN account. This is required for CAM to be able to create users, groups, metadata. Please note the “View Documents” permission is not required unless CAM is used for documents sync or Business Continuity.

        • Also, In future versions, CAM will support two different authentications 1. CAM authentication without download and delete document permission. Client NRTADMIn with download and delete document permission. This account will be stored in the Client’s AWS or Azure. Therefore CAM will never have direct permission to view or delete a document.

    NetDocuments

    • NetDocuments supports OAuth. CAM obtain the OAuth token from the NetDocuments Authentication dialog.

    • Permissions and Roles

      • You need to specify an Admin account with all permissions to create metadata, users & groups, workspaces, and folders.

    Office 365/Azure AD

    • Office 365 supports OAuth + Application authentication. CAM App is registered within the Azure Portal and assigned needed permissions. Then this App Id is used to obtain the OAuth token from the Office 365 Authentication dialog.

    • Permissions and Roles

      • You need to specify an Admin equivalent account all permissions to create team, SharePoint site, OneDrive, channel, groups, users, etc.

      • Minimum permissions for Azure AD are:

    Permission

    Description

    User.ReadWrite.All

    To add internal users via Azure AD

    User.Invite.All

    To add external users via Azure AD

    • After Authentication Configuration is completed, Object Configuration page is enabled on the right side of page.

    • Enter the following information on Object Configuration page

    System Limitations

    Aderant Expert Sierra

    Since Expert Sierra is on AWS and Aderant exposes the Database, the recommended way to connect is to leverage Aderant Cloud’s sync to an on-premises SQL database, and then use that as a source to CAM.

    Object Configuration

    Expand
    titleObject Configuration

    Select New Object Available options are:

    • Matter,

    • Metadata,

    • User,

    • Group,

    • Tab,

    • GroupMembership

    • After selecting New Object, the following fields are available to fill out to add new objects to be imported.

    Field

    Description

    Relative URL

    The url of the object in the source system

    Method

    The method to use when pulling the data. Options are: Get, Post, Put, Delete, Patch. For example, a GET, is a select of the data.

    Content type

    The type of the content in configuration format. E.g. Application/x-www-form-urlencoded, application/json

    Choose the system

    The system to create the object in. Available: Netdocuments, Imanage, or CAM

    For example if you are trying to write to iManage choose iManage.

    Info

    An exception to this is if you are using a custom system parameter. For example, if you want to set the createiniManage parameter to true and have other mapping configurations, it is best to set the system to CAM, and ensure the mapping is done for the createiniManage parameter.

    Suggested parameters

    The suggested parameters to set. Content-type, Authorization are available.

    Custom parameters

    Set custom parameters for the objects, with a field and value pair. Click +Add

    </>Encode

    If the record is base64 encoded, click encode.

    Header

    The request header. In configuration format, Application/x-www-form-urlencoded

    • View - Opens pop-up to view full Header contents.

    Additional Basic Object Configuration

    Additionally, you can include the API Call for same system to Fetch Data and Flattening Response containing Nested Objects by toggling ON. To configure see the below.

    Response

    The response pane.

    • View - Opens Pop-up to view full response content

    • Click Next to save Basic Object Configuration and it will also fetch the response. It contains Page Info i.e. Total Records and Total pages in the response. And records per page i.e. FirstRecord : 1 and LastRecord : 50

    Additional Basic Object Configuration

    • To configure Additional Basic Object Configuration, opens the accordion as follows:

    Fields

    Description

    Relative URL

    Specify the Endpoint URL. Based on the requirements you can replace actual Id to Uniqie_id in the Endpoint URL that helps to identify the backend process from where to replace id in the URL.

    Method

    Select Method type from the drop down to perform an action.

    • GET

    Mapping

    To set the mapping of fields used for creation of the object.

    For example, if you want to create an item in iManage, set the createiniManage parameter to true. It is best to set the system to CAM, and ensure the mapping here is done for the createiniManage parameter.

    Response pane is displayed for user to configure:

    Field

    Description

    Pagination By:

    Sorting Parameter to be used. Select from

    • Response URL

    • Query Parameters

    • No Pagination

    Pagination field

    Field to be used for pagination, select from the list or manually enter the value by setting Custom Value On.

    Result field

    Select object name.

     

    Info

    It is possible to add the following dynamic values for custom parameters for source system objects:

    • {{today}}

    • {{yesterday}}

    • {{last_week}}

    • {{last_month}}

    • {{last_run_time}}

    These values will be resolved at runtime and replaced with the proper value.

    • Click Save Fields and On successful response configuration, map the CAM fields and Web response by clicking Add Map Or Edit existing mapped fields.

    Eval Expressions

    For the Eval expressions within the Field Mapping, enter the javascript code for the expression.

    For example, the firm wants to create a workspace in iManage for the Create iManage Workspace attribute with the following criteria:

    If createiniManage parameter =true and the status of the workspace is not draft, then create the workspace. This will work in this script if the parameter createinimanage exists in the mapping.

    Code Block
    languagejs
    let arr = custom_attributes || [];
    let createInImanage = arr.find((value)=>{
      if (value.attribute_name === "Create iManage Workspace") {
        return true
      }else{
        return false
      }
    });
    
    if ((createInImanage && createInImanage.value !== "False") && status !== "draft") {
      exports.x = "1"
    }else{
      exports.x = "0"
    }

    Field

    Description

    Field

    Description

    CAM Field

    Select the CAM metadata from the drop-down. To assign a metadata, either click the drop-down menu and select from the list or manually enter the value, which will auto-complete if it is assigned in Administration>Metadata. Specifies how users can customize the name of the CAM Field -

    • Prefix - Users can add custom text to the beginning of the folder name

    • Custom Value - Users can assign a custom name to the folder

    • Suffix - Users can add custom text to the end of the folder name

    Web Response

    Select the source system metadata from the drop-down. Or Manually enter a value for the field by setting Custom Value On.

    Field Value

    Select the default value to be assigned to the CAM metadata. Manually enter a value for the field.

    Conditional Field

    Dynamically setting values: e.g. ClientId = {FieldNameFromSource}&MatterId={FieldNameFromSource}

    Eval Expression

    (Conditional Sync)

    Allows you to perform the conditional sync process using Eval expression. This process helps you to filter records coming from a source system such as the Google API.

    • Using the eval expression, you can now skip records in the sync. In the eval expression, you must provide JavaScript code in the form of conditional statements with exports.skip = true or false. You can use the Variable names from the JSON Web Response attributes.

    • You can find an example of the conditional sync feature implementation in the following code snippet. This code processes only those records whose name attribute starts with new-folder and skips all the other records. It helps you to filter records that start with new-folder.

    Code Block
    if(typeof name !== 'undefined' 
    && name 
    && name.startsWith("new-folder"))
    {
      exports.skip = false;
    }
    else
    {
      exports.skip = true;
    }
    
    • Click Save to save the mapping. A token is generated and sent to the DevOps team.

    • Get the token from the DevOps team and enter it in the Token Confirmation dialog box.

    • Click the Confirm button.

     

    • Once objects are configured, you can schedule the data sync between the source system and the target system. Click on the Schedule button to configure your data sync schedule.

    Expand
    titleSchedule

    Schedule

    Select Sync Repetition and set the time. CAM supports scheduling jobs on a minute-by-minute basis allowing job synchronization to occur more frequently when using source system configuration.

    • Minute

      • Set recurring time : Sync every {x} of Minutes

    • Hour

      • Set recurring time : Sync every {x} of Hours

    • Day

      • Choose Time : Sync at {x}

    • Year

      • Set Date and Time

    • Recurring every minute, 5 minutes or 15 minutes

    Click Confirm Schedule and you can view the Occurrence, Cron-Expression, Previous schedule, and Next Schedule.

    Click Sync Now to immediate data sync, which allows you to sync a specific object like User, Group, etc. or select All.

    Note: When CAM maintenance is going on, it stops scheduled job 30 mins before maintenance, and on initiating Sync Now will show warning message.

    Single/Multiple objects (Users & Groups, Metadata, etc.) can be independently scheduled for sync at a specific time interval.

    Note
    • If objects are rescheduled, then the time will be updated in the record.

    • It is not possible to schedule multiple objects according to different time durations.

    • Once Source System is configured it will be listed at Administration -> Source System Configuration.

    Quick Actions

    Action

    Description

    View

    Shows the configuration details.

    View Jobs

    Status of scheduled Jobs.

    Note

    A limit on the number of jobs a tenant can submit in Source System Integration now applies. The limit is 50,000 jobs. An error will warn the user on the limit, and any new Source system jobs will not be submitted for processing until the batch completes. This eliminates newer jobs continuously filling the queue or causing timeouts on the current original job.

    Upload Logo

    Logo to display for source system.

    Export

    System Configuration is exported at JSON file.

    Note: To Import the configuration file click on hamburger sign at top of the page and select Import Source System.

    Delete

    Delete the source system.

    Pagination

    For pagination, use the CSV Parameters for Source Systems here to set pagination. The parameters are supported for GET and POST commands.

    For example, here’s how to setup pagination for Simple Legal:

    Info

    It is possible to add the following dynamic values for custom parameters for source system objects:

    • {{today}}

    • {{yesterday}}

    • {{last_week}}

    • {{last_month}}

    • {{last_run_time}}

    These values will be resolved at runtime and replaced with the proper value.

    Role Permission Mapping

    CAM roles can be mapped to the external system role.

    Permission Mapping

    Set permission based on CAM Roles. Common CAM roles are following:

    • Admin - System administrators responsible for CAM User Management and Workspace Management

      For e.g. An user added as: alexey.marcus@prosperoware.com|true#23/12/2019*Admin$true

    • Editor - CAM users with Edit permissions to access CAM Workspace Management

      For e.g. An user added as: alexey.marcus@prosperoware.com|true#23/12/2019*Editor$true

    • Watcher - CAM users with Read permissions only to access CAM Workspace Management

      For e.g. An user added as: alexey.marcus@prosperoware.com|true#23/12/2019*Watcher$true

    • Deny: CAM users with the Deny rights gives no access to the object. For e.g. An user added as: alexey.marcus@prosperoware.com|true#23/12/2019*Deny$true

    Examples are as follows:

     Users:

    Adding an Admin ( iManage Full Access) bob.bradely@demofirm.com|true#23/12/2019*Admin$true

    Adding an Editor (iManage Read/Write access)

    firstnamelastname2@firmname.com|true#null*Editor$true

    Adding a Watcher (iManage Read only)

    firstnamelastname3@firmname.com|true#null*Watcher$true

    Denying Access (iManage No Access)

    firstnamelastname4@firmname.com|false#null*Deny$true

    Groups:

    For example, adding an editor group

    PartnersGroup|true#11/3/2021*Editor$true

     

    Info

    Note: Dates are based on your system setting found here: Admin->Settings.

    •  If multiple entries are included in this column, separate each entry by a comma.

    • firstnamelastname@firmname.com|true#null*Admin$false,Group4|false#null*Deny$true

     Click on the hyperlink of the CAM Role to show the CAM permissions available for the role.

    Info

    The permissions for these roles can only be edited after the server information has been saved. If the server details have not been saved, the Edit button will be grayed out. If hovered over, a tooltip will warn users about this.

    Click on each type of Security Role to update their respective permissions.

    Read

    This allows access to only view documents, properties /metadata etc

    Read Write

    This allows full access to the document (view and edit), but limited control on properties /meta-data and no ability to change security (including for the folder, workspace etc)

    Full Access

    This allows full access to the document (view/edit/share) and full control over properties /meta-data and also the security (including for the folder, workspace etc)

    Managing Files of Source System Integration

    In V2 of the Source System Integration, the Jobs submit JSON files instead of CSV files in the backend to avoid overloading the queue processor.

    Old Version Compatibility

    If a firm requires the older version of Source System Integration, V1, make the following changes to the appsettings.config file:

    Code Block
    \<setting name="v2Enabled" serializeAs="String"\>
    
    \<value\>False\</value\>
    
    \</setting\>
    Tip

    We recommend using the V2 version of Source System Integration for more efficient processing!

    New Version Features

    • In addition to the new submission in JSON, there is a new folder where those CSVs are stored when the JSONs are uploaded. This folder is called newCSV. The CSVs are created and then converted from these files in this folder to JSON. If a job fails, this would be the folder that contains the JSON files to troubleshoot.

    • Generated CSVs still reside in the generatecsv folder for all jobs.

    • Archived CSVs still reside in the archivecsv folder for any successfully completed jobs over time.

     

     

    Related Topics

    iMange | NetDocuments | M365 |