MS Teams Onboarding

The onboarding process is used to connect an existing MS Teams tenant to the Fusion platform so that it can make use of our voice services. It involves different steps to complete and sets data in different subsystems. To be completed, it requires the following information:

• Credentials from an administrator account for this MS Teams tenant

These credentials have first to be provided in Fusion system by using this API

About Credentials

In order to use the provisioning chain, the administrator account provided must have multi factor authentication turned off

Once this is provided, the following steps are performed as shown in the illustration below:

0. The tenant is created in the SRE as a reference for enabling voice services
1. An application is set as a service principal in Microsoft Azure AD. This application holds necessary and sufficient rights to allow further provisioning through MS Graph API's. On the SRE, a MS Graph gateway is created that will use this newly created application
2. A new domain is created on Office 365 for the tenant. This domain will be used to route voice calls towards direct routing. This newly created domain will undergo Microsoft domain validation by inserting a provided TXT DNS record at domain registration. This DNS TXT record will be inserted into supported DNS services and a check loop will be started until domain validation is complete
3. An extra E-mail service will be added to the created domain and required DNS entries to activate it will be added to the DNS services
4. In order to complete voice activation for the domain, a dummy account will be created for the tenant and an available E1 / E3 / E5 license will be assigned to it
5. The final step creates voice direct routing data in Microsoft Teams to apply configuration required to perform correct routing of voice calls

Preparing MS Graph integration

Prior to onboard an MS Teams tenant, a powershell integration script has to be run in order to create an Azure AD application. This application will contain sufficient rights to run the set of MS Graph API's and powershell commands required to perform Fusion's tasks. This script will ouput the MS tenant ID, application ID and application secret that will be used to trigger this API and complete the pre-requisites for onboarding an MS Teams tenant. This API may also be used without passing the MS tenant ID to update current azureAD application integration (useful in case the password has expired and has to be updated).

Request

Endpoint

POST /api/v01/draas/{draas_instance}/tenants/{uuid}/subscriptions/{subscription_id}/msteams/applications

Authorization

Required role

tenants.instance.subscriptions.instance.msteams.applications.create

Path Parameters

Parameter	Type	Description
draas_instance	string	See common parameters
uuid	string	A system generated unique ID (UUID) identifying the tenant to which the subscription belongs
sub_id	string	A system generated ID identifying the subscription for which you want to prepare the onboard the MS Teams tenant

URL/Query parameters

N/A

Body

Parameter	Type	Description	Required
msTeamsTenantId	string	MS Teams ID as found in Azure AD. Also returned by the integration script. Optional in case the integration already exists and you just want to update it	no
applicationId	string	Application ID as found in Azure AD. Also returned by the integration script	yes
secret	string	Application secret as found in Azure AD. Also returned by the integration script	yes

Example

{ 
    "msTeamsTenantId": "27b418d0-b197-483d-a0b8-da90407a92c4",
    "applicationId": "c035894c-81c3-49aa-8e3e-f245d9b3b846",
    "secret": "i6k8Q~e326mrmOiLBicPD_sGU236udICA3iieduo"
}

Response

Status codes

Parameter	Description
204	The application has been correctly created or updated
400	An error occurred while creating or updating the application. This can happen if the optional parameter MS tenant ID was not passed in case of a new integration or does not match a linked entry in case of an update
403	The API consumer doesn't have sufficient rights to perform this action
404	The path requested doesn't exists for the provided tenant and subscription ID's
500	Uncatched error on server side

Success

Body

N/A

Starting the onboarding process

Starts and chains the six steps required by the onboarding process. As this process is quite lengthy and can last from a couple of minutes to several hours, it is an asynchronous call. At API call, you will receive the transaction ID that you may use to follow execution of the asynchronous task. But more generally, this follow-up will be performed by the Checking the onboarding process API

Request

Endpoint

POST /api/v01/draas/{draas_instance}/tenants/{uuid}/subscriptions/{subscription_id}/msteams/wizard

Authorization

Required role

tenants.instance.subscriptions.instance.msteams.wizard.start

Path Parameters

Parameter	Type	Description
draas_instance	string	See common parameters
uuid	string	A system generated unique ID (UUID) identifying the tenant to which the subscription belongs
sub_id	string	A system generated ID identifying the subscription for which you want to onboard the MS Teams tenant

URL/Query parameters

N/A

Body

N/A

Response

Status codes

Parameter	Description
200	Asynchronous process has started
403	The API consumer doesn't have sufficient rights to perform this action

Success

Body

Parameter	Type	Description	Conditional?
id	integer	The transaction ID of the started asynchronous process	no

Example

{
  "id": 214964
}

Checking the onboarding process

Checks the state of the asynchronous provisioning task started by Starting the onboarding process API.

Getting a HTTP 404 code

Note that if this API is executed shortly after the onboarding process has been started, it may return an HTTP 404 code. This is not an error as such but means that the base structure for the MS Teams tenant has not been initialized yet in Fusion database. This correspond to the preparation phase before Step 0 is executed.

Request

Endpoint

GET /api/v01/draas/{draas_instance}/tenants/{uuid}/subscriptions/{subscription_id}/msteams/wizard

Authorization

Required role

tenants.instance.subscriptions.instance.msteams.wizard.read

Path Parameters

Parameter	Type	Description
draas_instance	string	See common parameters
uuid	string	A system generated unique ID (UUID) identifying the tenant to which the subscription belongs
sub_id	string	A system generated ID identifying the subscription for which you want to onboard the MS Teams tenant

URL/Query parameters

N/A

Body

N/A

Response

Status codes

Parameter	Description
200	The wizard steps with their status is returned
400	The wizard has ended with an error
403	The API consumer doesn't have sufficient rights to perform this action
404	The path requested doesn't exists for the provided tenant and subscription ID's or the MS Teams tenant has not been initialized yet
500	Uncatched error on server side

Success

Body

Parameter	Type	Description	Conditional?
running	boolean	Set to true if the onboarding process is still running, false otherwise	no
wizardSteps	array	List describing the state of each of the six steps	no

Step Object

Parameter	Type	Description	Conditional?
step	integer	Number of the step	no
text	string	Text describing the purpose of the step	no
executed	boolean	Indicates if the step has been executed (true) or not (false)	no
status	object	The status of the voice routing settings. See Voice Routing Status.	yes

Example

{
  "running": true,
  "wizardSteps": [
    {
      "step": 1,
      "text": "Set a domain for the tenant and validate it against Microsoft",
      "executed": true
    },
    {
      "step": 2,
      "text": "Create a dummy account and associate an E1 / E3 / E5 license to it",
      "executed": false
    },
    {
      "step": 3,
      "text": "Create MS Teams routing policies and remove associated license from the dummy user",
      "executed": false,
      "status": {
        "pstn": {
          "DRaaS-PSTN-Usage": {
            "detail": "Cannot add these items to the collection as they conflict or have duplicate key/identity: Usage: DRaaS-PSTN-Usage",
            "status": "already_exists"
          }
        },
        "vr": {
          "Draas-VR": {
            "detail": "Identity Draas-VR already exists",
            "status": "already_exists"
          }
        },
        "vrp": {
          "World-DRaaS": {
            "detail": "Identity World-DRaaS already exists in Tenant scope",
            "status": "already_exists"
          }
        }
      }
    }
  ]
}

Update Voice Routing settings

Update Voice Routing settings.

Request

Endpoint

PUT /api/v01/draas/{draas_instance}/tenants/{uuid}/subscriptions/{subscription_id}/msteams/update_vrp

Authorization

Required role

tenants.instance.subscriptions.instance.msteams.update.vrp

Path Parameters

Parameter	Type	Description
draas_instance	string	See common parameters
uuid	string	A system generated unique ID (UUID) identifying the tenant to which the subscription belongs
sub_id	string	A system generated ID identifying the subscription for which you want to onboard the MS Teams tenant

URL/Query parameters

N/A

Body

N/A

Response

Status codes

Parameter	Description
200	The Update process has finished
400	The request has ended with an error
403	The API consumer doesn't have sufficient rights to perform this action

Success

Body

Parameter	Type	Description	Conditional?
status	object	The status of the voice routing settings. See Voice Routing Status.	no

Voice Routing Status

Parameter	Type	Description	Conditional?
pstn	object	The status of PSTN. See Voice Routing Status Information.	no
vr	object	The status of Voice Routes. See Voice Routing Status Information.	no
vrp	object	The status of Voice Routing Policy. See Voice Routing Status Information.	no

Voice Routing Status Information

The main key is the voice routing setting name and its value is the following properties:

Parameter	Type	Description	Conditional?
detail	string	The detail message	no
status	string	The status. Possible values are: ok, already_exists, errorin case of a generic error.	no

Example

{
  "status": {
    "pstn": {
      "DRaaS-PSTN-Usage": {
        "detail": "Cannot add these items to the collection as they conflict or have duplicate key/identity: Usage: DRaaS-PSTN-Usage",
        "status": "already_exists"
      }
    },
    "vr": {
      "Draas-VR": {
        "detail": "Identity Draas-VR already exists",
        "status": "already_exists"
      }
    },
    "vrp": {
      "World-DRaaS": {
        "detail": "Identity World-DRaaS already exists in Tenant scope",
        "status": "already_exists"
      }
    }
  }
}

Download custom "Create App" Powershell script

This API allows the customer to download the create_app.ps1 script, customized with the customer's group's configurations

Request

Endpoint

POST /api/v01/draas/{draas_instance}/tenants/{uuid}/subscriptions/{subscription_id}/downloads/create_app

Authorization

Required role

tenants.instance.subscriptions.instance.downloads.create_app

Path Parameters

Parameter	Type	Description
draas_instance	string	See common parameters
uuid	string	A system generated unique ID (UUID) identifying the tenant managing the subscription
sub_id	integer	Index of a subscription for which you want to onboard a Tenant

URL/Query parameters

N/A

Body

N/A

Response

Status codes

Parameter	Description
200	The script has been correctly generated
404	The path tenant / subscription doesn't exist
500	Uncatched error on server side

Success

Body

Parameter	Type	Description	Conditional?
fileName	string	The name of the generated file	no
fileBody	string	The content of the file encoded in Base64 format	no

Example

{
    "fileName": "create_app.ps1",
    "fileBody": "UmVhZC1Ib3N0IC1Qcm9tcHQgIlByZXNzIEVudGVyIHRvIGV4aXQi..."
}

Resetting the secret of a MS Graph application

In the case a secret password for an application created at integration time of the MS Tenant expires or changes, this API allows Fusion integration to reset current secret password with a new one created on Azure AD.

Request

Endpoint

POST /api/v01/draas/{draas_instance}/tenants/{uuid}/subscriptions/{subscription_id}/msteams/reset_secret

Authorization

Required role

tenants.instance.subscriptions.instance.msteams.secret.reset

Path Parameters

Parameter	Type	Description
draas_instance	string	See common parameters
uuid	string	A system generated unique ID (UUID) identifying the tenant managing the subscription
sub_id	integer	Index of a subscription for which you want to create or update the MS Teams administrator

URL/Query parameters

N/A

Body

Parameter	Type	Description	Required
applicationId	string	Application ID of the current integration as found on Azure AD and Microsoft graph integration on Fusion (MS Teams / O365 Tenant)	yes
secret	string	New secret generated on AzureAD for the current application integration	yes

Example

{
    "applicationId": "d46e9288-2029-4fd1-ac7b-f20749e61251",
    "secret": "L4y8Q~DfIwfxqPdinI5mOWWdq4YA9Pk9xaFMyboC"
}

Response

Status codes

Parameter	Description
204	The MS Teams application secret was successfully reset
400	Error while resetting the secret for the MS Teams application
403	The API consumer doesn't have sufficient rights to perform this action
404	The path tenant / subscription doesn't exist
500	Uncatched error on server side

Success

Body

N/A

Unlinking a MS Teams tenant

This API allows to unlink a MS Teams tenant from Fusion. Previously onboarded data will be erased. This is only possible if no user has direct routing voice services enabled on Fusion anymore. This call is synchronous while it may take some time to complete.

Request

Endpoint

POST /api/v01/draas/{draas_instance}/tenants/{uuid}/subscriptions/{subscription_id}/msteams/unlink

Authorization

Required role

tenants.instance.subscriptions.instance.msteams.unlink

Path Parameters

Parameter	Type	Description
draas_instance	string	See common parameters
uuid	string	A system generated unique ID (UUID) identifying the tenant to which the subscription belongs
sub_id	string	A system generated ID identifying the subscription for which you want to onboard the MS Teams tenant

URL/Query parameters

N/A

Body

N/A

Response

Status codes

Parameter	Description
204	The MS Teams tenant has been successfuly unlinked from Fusion
400	Error while processing the request
403	The API consumer doesn't have sufficient rights to perform this action
500	Uncatched error on server side

Success

Body

N/A

Get the list of available subscriptions for MS Teams tenant linking

When associating a Fusion tenant to a MS Teams tenant through a subscription, we usualy use the onboarding API. But with the linking API, we can simplify this process and associate an already onboarded MS Teams tenant to different subscriptions. This endpoint gives for the current tenant and subscription the linking candidates. Note that this API is only available to group, distributor or reseller admins as they onlty can associate MS Teams tenants that are in their tree of authority to the specified tenant / subscription combination.

Request

Endpoint

GET /api/v01/draas/{draas_instance}/tenants/{uuid}/subscriptions/{subscription_id}/msteams/sources

Authorization

Required role

tenants.instance.subscriptions.instance.msteams.source.list

Path Parameters

Parameter	Type	Description
draas_instance	string	See common parameters
uuid	string	A system generated unique ID (UUID) identifying the tenant managing the subscription
sub_id	integer	Index of a subscription for which you want to get the list of available onboarded MS Teams tenant

URL/Query parameters

N/A

Response

Status codes

Parameter	Description
200	A list of linked subscriptions with an already onboarded MS Teams tenant has been found
400	Error while processing the request
403	The API consumer doesn't have sufficient rights to perform this action or the admin level is not right
404	No MS Teams administrator found or the path tenant / subscription doesn't exist / MS Teams User doesn't exist
500	Uncatched error on server side

Success

Body

Parameter	Type	Description	Conditional?
sources	array	A list of linked subscriptions with an already onboarded MS Teams tenant	no

Linked Subscription

Parameter	Type	Description	Conditional?
subscriptionId	integer	Index of the linked subscription as found in the Fusion database	no
subscriptionName	string	Name of the subscription	no
tenantName	string	Name of the tenant holding the subscription	no

Example

{
    "sources": [
        {
            "subscriptionId": 2,
            "subscriptionName": "Operator Connect DEV",
            "tenantName": "Netaxis DEV"
        },
        {
            "subscriptionId": 53,
            "subscriptionName": "CBUR Test SUB",
            "tenantName": "CBUR Test Tenant"
        }
    ]
}

Link a subscription to an already onboarded MS Teams tenant

By using this endpoint, you can associate a Fusion subscription to another subscription that already has onboarded a MS Teams tenant. This allows different Fusion subscriptions to share the same MS Teams tenant through different license types, entitlements, phone numbers and views. Note that this API is only available to group, distributor or reseller admins as they only can associate MS Teams tenants that are in their tree of authority to the specified tenant / subscription combination.

Request

Endpoint

POST /api/v01/draas/{draas_instance}/tenants/{uuid}/subscriptions/{subscription_id}/msteams/link

Authorization

Required role

tenants.instance.subscriptions.instance.msteams.link

Path Parameters

Parameter	Type	Description
draas_instance	string	See common parameters
uuid	string	A system generated unique ID (UUID) identifying the tenant managing the subscription
sub_id	integer	Index of a subscription for which you want to create a link to an already onboarded MS Teams tenant

URL/Query parameters

N/A

Body

Parameter	Type	Description	Required
subscriptionId	integer	Subscription linked to the MS Teams tenant you want to link to	yes

Example

{
    "subscriptionId": 2
}

Response

Status codes

Parameter	Description
204	The MS Teams tenant was successfully linked to the subscription
400	Error while processing the request
403	The API consumer doesn't have sufficient rights to perform this action or the admin level is not right
404	The path tenant / subscription doesn't exist
500	Uncatched error on server side

Success

Body

N/A