Configuring your adapter
The developer framework is currently in BETA
This framework is in beta. Please submit a Github issue if you encounter any problems or have a question.
Each adapter provides a configuration that in some ways also acts as a manifest file. The config file not only provides key pieces of metadata to enable the framework to connect to the CRM, and display other properties to the user (name and so forth), but it also allows developers to customize the appearance of screens, add custom fields to various CRM object types, and more. Here is a list of things the config file enables for developers:
- Provide CRM connectivity and authorization details
- Define custom fields for:
- call logging and disposition
- SMS and messagig logging
- Customize the "Connect to CRM" or authorization screen
- Define custom contact record types/categories
- Customize the welcome screen for a given CRM
Config file
TODO - describe where the config file is
Configuration options
| Name | Type | Description |
|---|---|---|
urlIdentifier |
string | The URL for which this CRM will be enabled. When the CRM is enabled for a domain, the extension's organge quick access button will appear. |
name |
string | The name of the CRM. |
authType |
string | The supported auth type for the corresponding CRM. Only two values are supported: oauth and apiKey. |
authUrl |
string | Only used with authType equal to oauth. The auth URL to initiate the OAuth process with the CRM. |
clientId |
string | Only used with authType equal to oauth. The client ID of the application registered with the CRM to access it's API. |
canOpenLogPage |
boolean | Set to true if the corresponding CRM supports permalinks for a given activity/log. When set to true users will have the option view/open the activity log in the CRM from the call history page. When set to false, users will open the contact page instead. |
contactTypes |
ARRAY of string | CRMs often adopt unique vernaculars to describe contacts. Provide the enumerated list of contact types supported by the corresponding CRM. |
Customizing the welcome message
When a user installs the CRM extension for the first time and accesses it from their CRM, a welcome page or splash screen appears to the user. This screen can be very effective in educating the end user about how to setup and connect to the associated CRM.
Currently welcome pages are relatively simple, providing developers with the ability to direct users to two key resources:
- A URL to watch a video
- A URL to read documentation
"embeddedOnCrmPage": {
"welcomePage": {
"docLink": "https://ringcentral.github.io/rc-unified-crm-extension/",
"VideoLink": "https://youtu.be/pQgdsAR1UCI"
}
}
Customizing pages within the client application
There are a number of pages within the Unified CRM client application that often need to be customized in some way for the corresponding CRM. Those pages are:
- CRM authentication page
- Call logging form
- Message logging form
Authentication page
"auth": {
"title": "test CRM",
"content": [
{
"const": "apiKey",
"title": "apiKey",
"type": "string",
"required": true
}
]
},
"auth": {
"title": "Insightly",
"warning": "To manually connect, please go to Insightly User Settings and then copy info in API section over.",
"content": [
{
"const": "insightlyGetApiKey",
"title": "Get API Key",
"type": "string",
"uiSchema": {
"ui:field": "button",
"ui:variant": "contained",
"ui:fullWidth": true
}
},
{
"const": "apiKey",
"title": "apiKey",
"type": "string",
"required": true
},
{
"const": "apiUrl",
"title": "apiUrl",
"type": "string",
"required": true
}
]
},
Example custom auth page
Adding custom fields to logging forms
CRMs almost always have a set of fields associated with logging an activity that are relatively unique. Consider for example Clio, a CRM used by legal professionals, in which users link calls to "matters" (e.g. a "legal matter"). Where CRMs like Insightly link calls to opportunities. To account for this, the framework makes it easy to add new custom form fields to two key forms users interact with frequently:
- Call logging page
- Create contact page
For each page, you will define an array of additionalFields. Each additional field element consists of the properties below.
| Name | Type | Description |
|---|---|---|
const |
string | A unique key identifying the field. |
title |
string | The display name of the field. |
type |
string | The data type associated with the field. |
contactDependent |
boolean | Set to true if this field would change when the selected contact is changed, or false if the value is static. |
Custom call log fields
Set up associated deals as dropdown options:
- Christmas special A351
- Easter A22
- Anniversary C92
and address as free input field.
"callLog": {
"additionalFields": [
{
"const": "associatedDeal",
"title": "Deals",
"type": "selection",
"contactDependent": true
},
{
"const": "address",
"title": "Address",
"type": "inputField",
"contactDependent": false
}
]
},
Custom SMS log fields
Set up associated deals the same as call log
"messageLog": {
"additionalFields": [
{
"const": "associatedDeal",
"title": "Deals",
"type": "selection",
"contactDependent": true
}
]
}
Sample config file
Here is a sample config file that illustrates the full syntax and structure of the config file.
{
"serverUrl": "https://xxxx.ngrok.io",
"platforms": {
"testCRM": {
"urlIdentifier": "developers.ringcentral.com",
"name": "testCRM",
"authType": "apiKey",
"authUrl": "https://oauth.xxxxxx.com/oauth/authorize",
"clientId": "",
"canOpenLogPage": false,
"contactTypes": [
"TestContactType",
"Contact"
],
"page": {
"auth": {
"title": "test CRM",
"content": [
{
"const": "apiKey",
"title": "apiKey",
"type": "string",
"required": true
}
]
},
"callLog": {
"additionalFields": [
{
"const": "associatedDeal",
"title": "Deals",
"type": "selection",
"contactDependent": true
},
{
"const": "address",
"title": "Address",
"type": "inputField",
"contactDependent": false
}
]
},
"messageLog": {
"additionalFields": [
{
"const": "associatedDeal",
"title": "Deals",
"type": "selection",
"contactDependent": true
}
]
}
},
"embeddedOnCrmPage": {
"welcomePage": {
"docLink": "https://ringcentral.github.io/rc-unified-crm-extension/",
"VideoLink": "https://youtu.be/pQgdsAR1UCI"
}
}
},
"clio": {
"urlIdentifier": "app.clio.com",
"name": "clio",
"authType": "oauth",
"authUrl": "https://app.clio.com/oauth/authorize",
"clientId": "",
"canOpenLogPage": false,
"page": {
"callLog": {
"additionalFields": [
{
"const": "matters",
"title": "Matter",
"type": "selection",
"contactDependent": true
},
{
"const": "logTimeEntry",
"title": "Log time entry",
"type": "checkbox",
"contactDependent": false,
"defaultValue": true
}
]
},
"messageLog": {
"additionalFields": [
{
"const": "matters",
"title": "Matter",
"type": "selection",
"contactDependent": true
}
]
}
},
"embeddedOnCrmPage": {
"welcomePage": {
"docLink": "https://ringcentral.github.io/rc-unified-crm-extension/clio/",
"VideoLink": "https://youtu.be/pQgdsAR1UCI"
}
}
},"insightly": {
"urlIdentifier": "insightly.com",
"name": "insightly",
"authType": "apiKey",
"canOpenLogPage": true,
"contactTypes": [
"Lead",
"Contact"
],
"page": {
"auth": {
"title": "Insightly",
"warning": "To manually connect, please go to Insightly User Settings and then copy info in API section over.",
"content": [
{
"const": "insightlyGetApiKey",
"title": "Get API Key",
"type": "string",
"uiSchema": {
"ui:field": "button",
"ui:variant": "contained",
"ui:fullWidth": true
}
},
{
"const": "apiKey",
"title": "apiKey",
"type": "string",
"required": true
},
{
"const": "apiUrl",
"title": "apiUrl",
"type": "string",
"required": true
}
]
},
"callLog": {
"additionalFields": [
{
"const": "organization",
"title": "Organisation",
"type": "selection",
"contactDependent": true
},
{
"const": "opportunity",
"title": "Opportunity",
"type": "selection",
"contactDependent": true
},
{
"const": "project",
"title": "Project",
"type": "selection",
"contactDependent": true
}
]
},
"messageLog": {
"additionalFields": [
{
"const": "organization",
"title": "Organisation",
"type": "selection",
"contactDependent": true
},
{
"const": "opportunity",
"title": "Opportunity",
"type": "selection",
"contactDependent": true
},
{
"const": "project",
"title": "Project",
"type": "selection",
"contactDependent": true
}
]
}
},
"embeddedOnCrmPage": {
"welcomePage": {
"docLink": "https://ringcentral.github.io/rc-unified-crm-extension/insightly/",
"VideoLink": "https://youtu.be/5hWvVI12UAc"
}
}
}
},
"rcClientId": "",
"rcServer": "https://platform.ringcentral.com",
"redirectUri": "https://ringcentral.github.io/ringcentral-embeddable/redirect.html",
"version": "0.0.1"
}