Configuring your adapter's manifest
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.
An adapter's manifest file helps a developer to instruct the framework on how to interface with your adapter. It enables developers to customize the user interface within certain boundaries, enables authentication and connectivity with the target CRM and more.
Below you will find an explanation of the many properties found within a manifest file.
Turn on developer mode
To use a custom manifest, we'll need to turn on developer mode and assign a custom manifest url to the extension. Here's how:
- Open DevTools
- In console, execute
window.postMessage({type: 'toggle-developer-mode', toggle: true})
and reload the extension - In user settings, there's a section for
Developer settings
. Input your custom manifest url and save - Reload the extension to make it work
Basic properties
These basic properties
Name | Type | Description |
---|---|---|
author |
string | The author of the adapter. This is displayed to end users within the Chrome extension. |
platforms |
ARRAY of object | An array of platforms being integrated with. Each element of this array defines a different CRM. |
serverUrl |
string | The base URL the Chrome extension will used when composing requests to your adapter. The URL should utilize HTTPS and should omit the trailing slash (/ ). For example: https://my-adapter.myserver.com |
version |
string | The version of your adapter. This is displayed to end users within the Chrome extension. |
Platform configuration
Each manifest file contains an array of platform
objects. This is helpful for developers who manage multiple CRM adapters from the same server.
The platforms property is an associative array. Each key should be a unique identifier for the crm. The value of each element is an object with the following properties.
Name | Type | Description |
---|---|---|
name |
string | The name of the CRM. |
displayName |
string | The display name of the CRM. |
urlIdentifier |
string | The URL for which this CRM will be enabled. When the CRM is enabled for a domain, the extension's orange quick access button will appear. (* for wildcard match is supported) |
auth |
object | Contains all info for authorization. Details |
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 object | (Optional) CRMs often adopt unique vernaculars to describe contacts. Provide the enumerated list of contact types supported by the corresponding CRM. Each object has display and value . |
contactPageUrl |
string | A format string to open a CRM's contact page, e.g.https://{hostname}/person/{contactId} . Supported parameters: {hostname} , {contactId} , {contactType} |
embeddedOnCrmPage |
object | The rendering config for embedded page, explained here |
logPageUrl |
string | A format string to open CRM log page. Eg.https://{hostname}/activity/{logId} . Supported parameters: {hostname} , {logId} , {contactType} |
page |
object | The rendering config for all pages, explained here |
requestConfig |
object | Contains http request config for client extension, including timeout (number in seconds) |
The client-side authorization url that is opened by the extension will be: {authUrl}?responseType=code&client_id={clientId}&{scope}&state=platform={name}&redirect_uri=https://ringcentral.github.io/ringcentral-embeddable/redirect.html
Authorization
platform
has auth
object which has following parameters:
Name | Type | Description |
---|---|---|
type |
string | The authorization mode utilized by the target CRM. Only two values are supported: oauth and apiKey . Setting up auth is covered in more detail in the Authorization section. |
oauth |
object | Only used with type equal to oauth . It contains authUrl , clientId and redirectUri . |
apiKey |
object | Only used with type equal to apiKey . It contains page |
oauth paramters
| Name | Type | Description |
| 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. |
| redirectUri
| string | The Redirect URI used when logging into RingCentral (not the CRM). It's recommended to use the default value of https://ringcentral.github.io/ringcentral-embeddable/redirect.html
. |
| customState
| string | (Optional) Only if you want to override state query string in OAuth url. The state query string will be state={customState}
instead. |
| scope
| string |(Optional) Only if you want to specify scopes in OAuth url. eg. "scope":"scopes=write,read" |
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 (ONLY for
apiKey
auth) - Call logging form
- Message logging form
apiKey auth page
"apiKey": {
"page": {
"title": "test CRM",
"content": [
{
"const": "apiKey",
"title": "apiKey",
"type": "string",
"required": true
}
]
}
"auth": {
"type": "apiKey",
"apiKey": {
"page": {
"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
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.
"embeddedOnCrmPage": {
"welcomePage": {
"docLink": "https://ringcentral.github.io/rc-unified-crm-extension/",
"videoLink": "https://youtu.be/pQgdsAR1UCI"
}
},
"page": {
"callLog": {
"additionalFields": [
{
"const": "associatedDeal",
"title": "Deals",
"type": "selection",
"contactDependent": true
},
{
Custom SMS log fields
Set up associated deals the same as call log
"const": "address",
"title": "Address",
"type": "inputField",
"contactDependent": false
}
]
},
"messageLog": {
"additionalFields": [
{
"const": "associatedDeal",
"title": "Deals",
"type": "selection",
"contactDependent": true
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 under embeddedOnCrmPage.welcomePage
:
docLink
: A URL to read documentationvideoLink
: A URL to watch a video