When integrating a new application with your BetterCloud instance, the overall installation process is consistent. However, each integration is different, and may require varying levels and types of authentication. This article provides instructions for configuring and collecting all the information you need in order to add the RingCentral integration in BetterCloud.
BetterCloud requires the following authentication type when integrating with RingCentral:
- Username and Password (Basic HTTP Authentication)
You will also need to enter the following additional environment variables in order to successfully connect:
*Please note the following important requirements for RingCentral:
- The SCIM API is only available to RingCentral accounts on Office Premium and Ultimate plans.
- SCIM must be set as the current Directory Provider in your RingCentral Admin Portal Account Settings
- In order to successfully integrate you will need to create an app in RingCentral. New apps must first be created in a sandbox environment and have several API calls run against the sandbox before you will be able to move the app to production. This process may take some time, and is described below.
- You must request the “Edit Accounts” SCIM API permission from RingCentral Support before you will be able to successfully connect. The best time to do this is after you've created your app in your sandbox, and the required information is supplied below.
Username and Password
The username and password of the account you are using to authenticate. This account must have the ability both to edit and read accounts, as well as the permissions to create an app in the RingCentral developer portal.
Client Secret, Client ID, and Instance URL
Creating a Sandbox App
To begin the process of creating an app in RingCentral, navigate to the developer portal and login. Head to “Console” from the top menu.
Click “Create App.”
Provide an application name and description - these fields are both required.
On the next page set your Application Type to “Private” and your Platform Type to “Server-only (No UI).” This information is not editable later on, so be sure to set it correctly now.
Under the OAuth Settings you will be required to specify which permissions your app needs. We require that “Edit Accounts” and “Read Accounts” both be selected.
*Please Note: If you do not see the option to add “Edit Accounts,” you will need to contact RingCentral Support to enable the option. Go ahead and create the app, then refer to the following section.
Enabling the Edit Accounts Permission
If you can successfully select the Edit Accounts permission, you may skip this section. The Edit Accounts permission is considered an "advanced" permission, which RingCentral's support must manually enable before it appears as an option in your app's OAuth settings. Providing their team with all of the relevant information will allow them to assist you more quickly. Please send all of the following information when contacting them:
- Main Company Number
- Contact Phone
- Client ID (this is the unique ID of the app, available under the app's credentials once it has been created)
- Application Name
Promoting Your App to Production
Once you have created your app, its production status will be set to “Inactive.” RingCentral has several requirements for making API calls in your sandbox environment with a new app before it can be promoted to production. See the graduation requirements below:
In order to get started making the required API calls, head to the API reference section of RingCentral, under “Resources” in the developer console.
You will need to authorize the correct app before you can make calls.
The easiest call to make is a GET call, which uses the “Read Accounts” permission. This is the first option under the “Account” section. You can make as many repetitive calls here as you’d like - this will both help you meet your 20+ call requirement, and ensure you have a high percentage of successful calls.
Click “Try it out” to run the call. Using a “~” under “Input” runs the call against your own account. Ensure that you receive a 200 OK response in the Metadata on the right side of the page.
You will need to also exercise the “Edit Accounts” permission. The easiest way to do this is to simply delete a sandbox user (if you have a test user available). You may use other calls if you would prefer, but the following steps will show you how to delete a test user in your sandbox.
Navigate to “Provisioning” > “SCIM” > “Delete User.”
The ID of the user to delete can be found in the URL after clicking into a user's account settings in your sandbox. To navigate to your sandbox admin portal, open a separate window and head to the "Console" section of the developer portal, and select "Sandbox Accounts." Then click to open the "Online Account Portal."
From the sandbox portal, select "Users."
Then select the user you will be deleting. Their ID will populate in the URL.
Back in the API Resources, enter that value in the “Input” field, and click “Try it out” to delete the user.
You are required to make at least 5 calls from each endpoint, so in order to make enough calls from the SCIM endpoint, run at least 4 additional GET user calls. You may either enter an ID, or use the “~” symbol to retrieve your own account.
The graduation requirements are updated approximately every 15 minutes, so you may need to wait until your most recent calls are reflected.
Once you have met the graduation requirements, apply for production from the app’s dashboard.
Collecting Your Environment Variables
When your app has been approved, your production credentials will revealed. The API server URL (instance URL), Client ID, and Client Secret are all included. For the URL, enter only the information after “https://”.
Setting SCIM as your Directory Provider
Navigate to “Admin Portal” > “Tools” > “Account Settings” > “Directory Integration”
Set your Current Directory Provider to “SCIM”
Once you have added your integration, your username, password, Client Secret, Client ID, and Instance URL can be updated at any time, if necessary.