We automated the provisioning steps in a PowerShell script for you. It will connect to our environment and get the needed changes applied to your infrastructure.

Please read before you start

The PowerShell script needs to be run by a tenant admin TENANT ADMIN . Please note:

  • The script will automatically apply Required App Permissions used by Nimbus.
  • The following modules are used / installed on your machine when running the script.


    Module
    1MicrosoftTeams
    2MSAL.PS
    3Microsoft.Graph.Authentication
    4Microsoft.Graph.Applications
    5Microsoft.Graph.Identity.DirectoryManagement
    6Microsoft.Graph.Users
    7Microsoft.Graph.Users.Actions

  • We recommend executing the script with PowerShell 5.1 (you can check the version via the "Get-Host" command). Version 7 is causing frequent problems. (info) Also refer to the "Troubleshooting" section on the bottom of this page.
  • The script uses a checksum verification based on the MD5 algorithm - if you have policies like FIPS compliancy enabled on your computers which do not allow the usage of MD5, then you may encounter an error during the version check.

(lightbulb) Tip: The script run is also needed when certain Service Settings change (e.g. PSTN numbers & Team Name). Keep the script session window open if you want to test settings. By doing so you don't need to go through all steps again when you need to provision multiple teams.

Microsoft Graph PowerShell Permissions

The Microsoft.Graph.* modules which are used by the Provisioning Script require permissions that need to be granted for the Microsoft Graph PowerShell Enterprise application: 

PermissionPermission TypeGranted ByPurpose
Application.ReadWrite.AllDelegatedTenant AdminRead and write all applications
AppRoleAssignment.ReadWrite.AllDelegatedTenant AdminManage app permission grants and app role assignments
DelegatePermissionGrant.ReadWrite.AllDelegatedTenant AdminManage all delegated permission grants
Domain.Read.AllDelegatedTenant AdminRead domains
Organization.Read.AllDelegatedTenant AdminRead organization information
Users.ReadWrite.AllDelegatedTenant AdminRead and write all users' full profiles
openidDelegatedTenant AdminSign users in
profileDelegatedTenant AdminView users's basic profile
offline_accessDelegatedTenant AdminMaintain access to data you have given it access to

Below is an overview of our provisioning script

Provisioning - Step by Step

Script download

Get the provisioning script via direct link below. Pick the link depending on the chosen location:


Script Regions

(question) Which region do I pick? Pick the correct script according to the (future or already existing) region of your tenant data. Refer to Nimbus Installation > "Service Provisioning ". 


(question) What will this script do? Automate and guide you through the Azure-related setup on your Tenant. Refer to the detail steps below.

(lightbulb) You may have a look inside the script and compare the different scripts we provide, but manual edits are not required.
(lightbulb) When executed the script will check for updates and may request you to download the newest version.
(lightbulb) Once a Nimbus team has already been provisioned y ou can also find a script "Download" button located within the User Preferences (Portal).

Script Details

(tick) TENANT ADMIN To execute the script Tenant Administrator credentials must be provided (→ 'Global administrator' role). 

(info) Refer to the diagram above for an overview. During execution and depending on pending Service Settings changes the script will perform the steps below:

  • Connect to Microsoft Graph, Microsoft Teams and your Nimbus tenant.
  • Grant the needed consent for the main Nimbus application, this will allow Nimbus to read user and team details in the tenant and record voice messages if the latter is configured for the team. → See: Required App Permissions

  • Create, update or delete an Application Instance and grant the required consent to it to be able to set up conversations.
  • Associate or remove Phone System license (info) Refer to Installation Prerequisites > PSTN licensing for details.
  • Apply an Online Voice Routing Policy from the ones defined and selectable on your tenant. This is only required for Nimbus services which are using a Direct Routing phone number.
  • Add, update or delete PSTN phone number. (warning) Note that a PSTN number causes additional license cost by Microsoft. Get in touch with your local O365 integrator.
  • Lastly the script will apply Service Settings - either new or future changes made by you or any service team owners (e.g. a name, UPN, or phone number change).

    Pending changes on a Service will inform about a necessary Script-rerun

    Done?

    → After execution, the Script reports back to Nimbus. If everything was successful all changes are reflected in the Service Settings.


    (lightbulb) Please allow for a few minutes before making calls to a newly (re)configured Application Instance or PSTN number as it might take a moment for Microsoft Azure services to synchronize all the changes.
    (lightbulb) Note that a rerun of this script is necessary for every additional Service and/or within your tenant.

Script Execution

  1. Execute the script and wait for the connection to Microsoft Graph, Teams, and Nimbus. (lightbulb) If the script is not up-to-date you will be requested to download the latest version.
  2. When requested to login, provide your tenant admin credentials.

    Login request
  3. You may be asked for your admin consent on the first run of the script. (lightbulb)When using a Global Admin account you can grant these Permissions for your entire organization, so other administrators do not need to repeat this step.

    Permission request dialogue
  4. The script will now proceed to grant Required App Permissions to the Nimbus App on your tenant:

    1. If this has already been done by a tenant admin in the Nimbus Installation chapter, this is not required again.

    2. Potentially missing calling bot permissions (required e.g., for establishing sessions and posting Adaptive Cards to your Teams) will also be regranted automatically.

      Permission grant process
  5. The Script checks whether any Nimbus services have been added, changed in the respective Service Settings , or deleted since the last time the script was run.

  6. All services with pending changes will be shown as either Delete, Create or Update.
    You can then choose one of the two options.
    I - per Team individually - you can inspect and confirm each change.
    A - for all Teams - all changes are auto-confirmed. (warning) Please note that PSTN licenses will be applied automatically as long as they are available - first come, first serve base. 
  7. Carry on with the next step for further technical details.

PSTN Licenses and Voice Policies

(tick) The following steps apply only if your Nimbus service has a PSTN number assigned to it via its Service Settings.


PSTN License

The script allows you to choose how you would like to apply the required Phone System license to a service (Application Instance).

You have the following options:

  • Let the script assign a 'Microsoft Teams Phone Resource Account' license automatically
    (warning) Ensure that your account has the required permissions to perform this action.
  • Manual Assignment
    → The script will wait for you to manually assign the license (e.g., via the M365 portal), then performs a check after you have pressed Enter.
  • Skip (no license and phone number will be assigned)

(lightbulb) Via the same script functionality you can also remove Phone System licenses from Nimbus services.

Voice Policy

The script will ask before any Online Voice Routing Policy should be applied to a service (Application Instance).
(info) This is only required if your service is using a Direct Routing phone number. If you are using a phone number provided through Calling Plans or Operator Connect, you can skip the voice policy assignment.

You have the following options:

  • When No is selected, no changes will be applied.
  • When Yes is selected, available Online Voice Routing Policies from your tenant are polled.
    → You will be requested to confirm the Online Voice Routing Policy name to assign it.
    (info) When choosing the policy, please use the full name including "Tag:"

(lightbulb) The script will only ask for an Online Voice Routing Policy assignment when a phone number is added or changed. If you wish to manually change the policy later on, you can do this via the Grant-CsOnlineVoiceRoutingPolicy command.

Script Conclusion and Rerun

  1. When everything runs as expected you will see green DONE indicators and the script finishes.

    Script conclusion
  2. (lightbulb) At the end you will be asked if you want to rerun the script:

    1. You want to keep the script instance open until all Service changes are complete, so you don't need to authenticate again.

    2. For each further pending change in the General Service Settings  (e.g. in Dialogue with your Service Team Owners) the PowerShell instance can be run again until you are satisfied with the results.

Verifying changes via Test Call

(tick) Allow for at least 5 minutes after applying Team changes before making the call. 

  1. To test the functionality, team members should be available for the called team and be set to "Active" in their Dashboard
  2. On the Service Team you want to test, open the General Service Settings

  3. Click on " Test Call " → The UPN of the service will now be called via Team Client.

    Test Call in the Service Settings.

    (lightbulb) You can test this with 2 different Microsoft Teams client accounts in separate browser windows to simulate this call on your own as both caller and recipient.

    (lightbulb) If you have assigned a PSTN license / phone number to the service it is also recommended to test calling it.

PSTN Limitations


Transfer to PSTN limitation


Out-of-the-box, Nimbus and affiliated addons can only perform PSTN transfers according to Microsoft's licensing and constraints.


Which PSTN license do I need to acquire?

(tick) As a tenant administrator you need to acquire the following licenses and assign them to the application instance of the respective Nimbus SOURCE service (team) that will act as PSTN transferor:

Your SetupRequired License
Direct Routing"Microsoft Teams Phone Resource Account"
Calling Plan"Microsoft Teams Phone Resource Account"
+ "Microsoft Teams Domestic Calling Plan" or "Microsoft Teams Domestic and International Calling Plan" or "Microsoft Teams Calling Plan pay-as-you-go"
+ "
Communication Credits" (if these aren't already included as part of your plan)
Operator Connect
"Microsoft Teams Phone Resource Account"


(warning) As of 2023 "Microsoft Teams Phone Standard" licences are no longer supported by Microsoft. Previously those licenses were viable for Nimbus. → Regardless if you are using Direct Routing, Calling Plans, Operator Connect - the "Microsoft Teams Phone Resource Account" license is now always required

(warning) Please note that Luware staff cannot make recommendations on which license plan is best suited for your needs. Depending on your scenario, additional Teams App licenses may be required. Exact details are to be discussed with your Microsoft contacts.


(info) Also see: https://learn.microsoft.com/en-us/microsoftteams/teams-add-on-licensing/virtual-user


How does PSTN licensing affect Service and Call Transfers?

Assuming that Service A has a PSTN license assigned - but further Services don't - the following scenario may unfold:

  • Scenario A - Service A workflow is configured to transfer the caller to Service B. The license of Service A is used, the PSTN transfer occurs. The PSTN license is re-used throughout further transfers to Services C..D...x.
  • Scenario B - Service B is called directly instead. Now the workflow of Service B attempts a redirect to either service A or transfer to C. The PSTN transfer fails due to a missing license on Service B.

Learnings

  • For one first-level-response Service: If you handle first-response calls always via the same Service you need a PSTN license for that particular first-level Service.
  • For multiple first-level-response Services: If you handle first-response calls always via multiple Services you need a PSTN license for all those first-level Services .
  • Nimbus will attempt to use the PSTN license of the first service that responded to a call, regardless of how many further internal service transfers are performed thereafter.
  • If no PSTN license is found on a service that requires it for a transfer, the transfer task will be considered as failed and be treated as such by the system (e.g. workflow exit announcement, reporting "transfer failed" outcome).

(warning) Note that handling and tracking of running cost for PSTN licenses is outside of Luware support scope.
If you require assistance in extending and/or configuring your Nimbus services for PSTN our support will gladly assist you:


(info) Refer to the external reference: Microsoft Teams PSTN connectivity options and Microsoft Teams add-on licenses.

Troubleshooting & Known Issues

First-time script execution

When the script is run for the first time on a given machine it will try to install the required PowerShell modules if they aren't already available. This may require you to run the script as a local administrator:
→ Right click on the "Windows PowerShell" item in Windows search and select "Run as administrator". 

IssueAnalysis / Workaround

"Script cannot be loaded because running scripts is disabled on this system."

This error will occur if your local script execution policy does not allow running signed scripts.
→ Changing execution policy to "RemoteSigned" will help to solve this, please check the Microsoft Documentation for more details.

During Service Name Change: The script may encounter an error when trying to update the display name of a service

→ Change the Display Name of the User Object via Microsoft 365 or Azure AD. This information will be synchronized with Microsoft Teams. This process can take a few days until the changes are visible in the Microsoft Teams Client.