Configuring Provisioning for BT Cloud Phone

This guide provides the steps required to configure Provisioning for BT Cloud Phone and includes the following sections:

Features
Requirements
Configuration Steps
Schema Discovery
Bi-Directional Sync (Attribute Level Mastering)
Provisioning Errors
Troubleshooting Tips

Features

The following provisioning features are supported:

Import New Users
Import Profile Updates
Import User Schema
Push New Users
Push Profile Updates
Push User Deactivation
Profile Master

Requirements

Before you configure provisioning for BT Cloud Phone, check the following requirements:

To enable Provisioning Features, you need to have the valid BT Cloud Phone Admin account.
In order to user the Profile Master functionality, you need to have the following feature flags enabled. Contact Okta Support to have these enabled for your org:
- ALLOW_BOTH_PROFILE_MASTERING_AND_PUSH
- ATTRIBUTE_LEVEL_MASTERING
Contact BT Cloud Phone to enable Directory Integration for your corresponding account.
If you'd like to test using the BT Cloud Phone UAT environment, you can do so using the BT Cloud Phone UAT application available only in Okta Preview. If you do not have an organization in Okta Preview, contact Okta.

Configuration Steps

Configure your Provisioning settings for BT Cloud Phone as follows:

Check the Enable API Integration box, then click Authenticate with BT Cloud Phone:

Note: If you are setting up the BT Cloud Phone UAT application in Okta Preview, you will need to plug in the API Base URL under the General tab. The URL is https://api.eurouat.ringcentral.com.
Enter your BT Cloud Phone Admin account credentials, then click Log In at the pop-up window:
Select To App in the left panel, then select Provisioning Features you want to enable.

Note: The authenticated session is valid for one month since last usage of provisioning features. If you will not use provisioning for more that one month, you'll have to re-authenticate the app.

Refer to the Schema Discovery section for information about adding extra user attributes.

Bi-directional Sync (Attribute Level Mastering)

While either Okta or Active Directory are the sources of truth for most attributes in a user profile, in the case of a BT Cloud Phone deployment, the Direct Number and Extension information comes from BT Cloud Phone. To support this, you need to setup bi-directional sync for these attributes so that values can flow back to Okta or Active Directory.

To achieve this, do the following:

Contact Okta Support to enable the ALLOW_BOTH_PROFILE_MASTERING_AND_PUSH feature flag.
Add the Direct Number and Extension Number attributes via Schema Discovery to the AppUser profile by navigating to Profile Editor > BT Cloud Phone > Add Attributes.
Set mappings via the Profile Editor in the BT Cloud Phone to Okta section:
1. You should have the following configured:
  - appuser.userName > login
  - appuser.firstName > firstName
  - appuser.lastName > lastName
  - appuser.userName > email
2. Configure the mapping for directNumber and extensionNumber:
  
  For example, map a combined value to the primaryPhone attribute in the Okta profile – the format is [directNumber]#[extensionNumber]:
```
(appuser.directNumber != null ? appuser.directNumber : "") + "#" + appuser.extensionNumber
```
For the primaryPhone attribute, you need to set the BT Cloud Phone as the Master:
- Click on the Primary phone attribute in the Profile Editor.
- Under Master priority, select Override profile master.
- Add BT Cloud Phone as the master as shown below.
- Click Save Attribute.
Enable the Profile Master provisioning feature for the application.

Note: Make sure you have the right master priority set if there are other Profile Master apps. You can do so by going to Directory > Profile Masters.

Schema Discovery

The following list is the minimum set of attributes needed from Okta into BT Cloud Phone:

OKTA	TO > BT Cloud Phone
user.firstName	firstName
user.lastName	lastName
user.email	email
user.mobilePhone	mobilePhone
user.streetAddress	street
user.city	city
user.state Note: Make sure State in AD/Okta is in proper ISO format	state
user.zipCode	zip
user.countryCode	country
user.department	department

Provisioning Errors

ERROR MESSAGE	EXPLANATION
The [${parameterName}] is invalid. Please correct the parameter in Active Directory.	Values coming from Active Directory are not right. Please correct the values. Make sure all the values are right.
Resource for parameter [${parameterName}] is not found.	Value is missing in Active Directory. Please correct it.
JSON can not be parsed. Please check your data AD and correct it.	JSON can not be parsed. Please check your data AD and correct it.
Service Temporarily Unavailable. Please check back later.	Please check back again in sometime. Issues on Okta.
Extension already in use. Please go to BT Cloud Phone's web portal and see what extensions are available.	Extension already in use. Please check in service web if extension is available or not.
user.city	city
Extension number is duplicate. Please correct in Active Directory if you have an extension field. Otherwise edit it in the BT Cloud Phone Service web portal	To bulk edit extensions in the BT Cloud Phone web portal. Please go to User Management > edit extensions and follow the instructions to edit.
More than one record found for Email: [email]	BT Cloud Phone has more than one user record for the given [email]. Since Okta uses email address as the unique identifier per user, you need to ensure that does not have duplicate users with the same email address.
user.countryCode	country
user.department	department

Troubleshooting Tips

Okta can only import one directNumber value, so if a user has several numbers set in [AppName], only the first one will be imported.