Source System Integration

Overview

The Source System Integration 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.

Source System Limit

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.

Please Consider: If you have a large number of jobs that you need to run, you could start all jobs at the same time and let Source System Integration work through the backlog. However, this results in poor performance and even failure if the number of jobs is too high. The first few jobs are put into the Running state and the remaining jobs are put into the Queued state. This could make a lot of jobs fail even when they aren’t running and that can negatively impact the other jobs that are running.

Please work with your partner or professional services consultant to discuss best practices of managing and queueing jobs to that limit.

Configuring A New Source System

Click on the Administration tab.
Click on the Source Systems Configuration panel.
Click on the actions menu on the upper-right corner and select New Source System.
Input the basic details in the System Basic Configuration screen that will show (see screenshot below).

Field	Description

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. Note: Depending on the Authentication type (Fetch OAuth, OAuth), different configuration options will be displayed on bottom-left of the page. The following sections go over the details for each type.

Click on Save System.

Authentication Configuration

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.

Enter the following information for the Auth Token Configuration:

Field	Description

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.

Click Next.
For the App Authorization, enter the following information:

Field	Description

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.

click Validate, this allows the information to be validated before saving. If there are problems with the information, the errors will display.
For the Refresh Token Configuration, enter the following details:

Field	Description

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.

Click on Save.

Authentication type Fetch OAuth

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

for the Fetch OAuth Configuration, enter the following information:

Field	Description

Field	Description
Auth URL	This is a required field. Authorization URL of the source system.
Client ID	This is a required field. Client ID of the source system.
Client Secret	This is a required field. the Client secret of the source system.
Grant Type	This is a required field. The way an application gets an access token E.g. Authorization Code, Client Credentials or Password.
Username	Enter the username.
Password	Enter a password.

Click on Complete.

Authentication type UserId/Password

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

For the User and Password Configuration, enter the following information:

Field	Description

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.

Click on Confirm.

Note: For all authentication types, a warning will appear if an incorrect configuration is entered and CAM 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.
For Permissions and Roles, you need to specify the NRTADMIN account. This is required for CAM to be able to create users, groups, and metadata. Please note the “View Documents” permission is not required unless CAM is used for document sync or Business Continuity.
In the future, CAM will support two different authentications:
- CAM authentication without permission to download and delete documents.
- Client NRTADMIn with permission to download and delete documents. 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 obtains the OAuth token from the NetDocuments Authentication dialog.
For 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

Office365 supports OAuth + Application authentication. The CAM App is registered within the Azure Portal and assigned the needed permissions. Then, this App Id is used to obtain the OAuth token from the Office365 Authentication dialog.
For Permissions and Roles, you need to specify an Admin-equivalent account for all permissions to create teams, SharePoint sites, OneDrives, channels, groups, users, etc.
The minimum permissions for Azure AD are:

Permission	Description

Permission	Description
User.ReadWrite.All	The permission is required to add internal users via the Azure AD.
User.Invite.All	The permission is required to add external users via the Azure AD.

After the Basic Authentication Configuration is completed, the Object Configuration panel is enabled on the right side of the page.
Enter the information on the Object Configuration page (see next section).

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

Select New Object. The available options are as follows:

Matter
Metadata
User
Group
Tab
GroupMembership

Expand the corresponding New Object section and fill out the available fields to add new objects to be imported.

Field	Description

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.
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. This will also fetch the response which 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

Expand the Additional Basic Object Configuration section. The following screen is shown for you to input the details:

Fields	Description

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.

The Response pane is displayed for the user to configure:

Field	Description

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.

Click Save Fields.
After a 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.

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

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 the recurring time: Sync every {x} of Minutes.
Hour. Set the recurring time: Sync every {x} of Hours.
Day. Choose the time : Sync at {x}
Year. Set Date and Time.
Recurring every minute, 5 minutes, or 15 minutes.

Click Confirm Schedule to view the Occurrence, Cron-Expression, Previous Schedule, and Next Schedule.
Click Sync Now to immediately sync data, which allows you to sync a specific object like User, Group, etc., or select All.

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

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

Quick Actions

Action	Description

Action	Description
View	Shows the configuration details.
View Jobs	Status of scheduled Jobs. Note: In Data Uploader, or SSI or CAM in general, When a provisioning job for a team or channel or site is received, CAM creates a separate job for each tab or app in addition to the Team creation or provisioning job. For provisioning users, or groups or workspaces or folders, there is only one job when bulk updating or creating records from DU or SSI. E.g. one record will show for Data Upload. Then a record shows for the subsequent action of Create Workspace if the job was creating workspaces from DU.
Upload Logo	Logo to display for source system.
Export	System Configuration is exported at JSON file.
Delete	Delete the source system.

Pagination

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

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

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/2019Admin$true* Adding an Editor (iManage Read/Write access) firstnamelastname2@firmname.com\|true#nullEditor$true Adding a Watcher (iManage Read only)* firstnamelastname3@firmname.com\|true#nullWatcher$true Denying Access (iManage No Access)* firstnamelastname4@firmname.com\|false#nullDeny$true Groups:* For example, adding an editor group PartnersGroup\|true#11/3/2021*Editor$true
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:

\<setting name="v2Enabled" serializeAs="String"\>

\<value\>False\</value\>

\</setting\>

New Version Features

In addition to the new submission in JSON, there is a new folder where the new 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.