Lots of companies use some kind of on-call rotation. Every week a different person is responsible for managing the calls after hours.

Companies used to hand out mobile phones to the on-call engineer, but this can be pretty cumbersome.

With Skype for Business we can setup call forwarding to a mobile phone. The company can provide an office-phone number to his customers. During office hours, this phone is answered by the engineers present at the company, after-hours the calls to this phone number are forwarded to the mobile phone number of the engineer. There are two main advantages to this system:

• The employee doesn’t have to juggle between two phones.
• The customers don’t know the mobile phone number of the employee.

To configure call forwarding in Skype for Business, you need to log in as the user and change the settings in the Skype for Business Client. You could assign someone in your organization to change the forwarding settings on a weekly/daily basis. But I prefer to use Powershell for this ;).

The only way to change forwarding settings through a script in Skype for Business is with the UCWA API. This API is available for Skype for Business Online and on-premises. My script is configured to work with Skype for Business Online.

Before we can configure Skype for Business settings, we need to authenticate to AzureAD. We can use OAuth2.0 to request a token and log into AzureAD. Using OAuth2.0 requires you to create an application in AzureAD.

Creating an AzureAD Application

The first step is creating theapp registration in AzureAD. This should be a Native application and you only need to tweak two settings:

• Enable Oauth2ImplicitFlow in the manifest
• Granting permissions to configure Skype for Business settings for all users.

Authenticate to AzureAD

Authenticating to AzureAD with UCWA consists of four steps:

• Get the base URL
• Receive a token
• Get the application URL
• Get an application token

 

Get the base URL

The first step is to get your Skype for Business base URL. This is done through an HTTP POST to your Skype for Business Autodiscover URL (lyncdiscover.domain.com). The baseURL has the following format: https://webdirX.online.lync.com. We will use this baseURL in a bit.

Receive a token

Use a HTTP POST function against ‘https://login.windows.net/common/oauth2/token’ to receive an AzureAD Token. This token will be used to authenticate yourself against AzureAD. Specify the Application ID of the AzureAD Application you created and the credentials of the user you want to change the forwarding settings for. More information can be found in The Microsoft Docs.

Get the application URL

Next up, use this token to request the application URL of UCWA. This URL is different each time, so you need to perform this step each time you execute the script. Perform an HTTP GET against your S4B baseURL  and provide the AzureAD token you just received.

The response for this HTTP GET is not consistent. Sometimes you will receive the application URL but 9 times out of 10 you will receive a redirection URL. Execute the same HTTP webrequest, but with the redirection URL instead of the ApplicationURL. I used a recursive function for this. This part is not in any Microsoft documentation and can be pretty tricky if you don’t know what to expect.

Get an application token

This step is almost the same as the second one, where we requested an AzureAD token. The token we will receive now is different from the previous because the token has permissions to create an application resource and make changes with UCWA.

The only difference from step 2 is that you need to provide the application URL you got in the previous step as an HTTP POST parameter.

Creating an application resource

There is just one final step before we can begin configuring our Skype for Business Settings through UCWA. This final step consists of creating an application resource in UCWA. This will return a few URLs/endpoints, one of them is the ‘me’ URL which we will use to change settings for the current logged-on user. Execute an HTTP post to the application URL you got in the previous step and provide the application token and the following post parameters:

@{culture='en-us';endpointId="xxxxxxxxxx";UserAgent='PowerShell'} 

• Culture: is the language of your choice
• Endpoint ID: a unique ID of your choice, every application should have it’s own EndpointID
• UserAgent: The agent you use to execute the commands

We will use the ‘me’ URL in the next step.

Configure Skype for Business settings through UCWA

There are lots of different configuration options available in UCWA, a list of them can be found in the MS Docs. We need the ‘callForwardingSettings’ part.

Changing the number itself is actually pretty simple, the hardest part is getting the format of the number correct.

Use the following function to set the forwarding number of the current user:

Invoke-WebRequest -Method POST -URI "$shortroot$meurl/callForwardingSettings/immediateForwardSettings/immediateForwardToContact?target=tel:$number" -Headers @{"Authorization"="Bearer $tokenAppl"} -ContentType "application/json" 

The number should be in the format: 00{countrycode}{number}.

Putting it all together

Use the steps above to create your own application that can be run as a scheduled task or a job in Azure Automation. I have created a lot of different scripts for this type of use case, each one with it’s own requirements.

Some get their data from a CSV-file, others from an Navision database. Some customers use this script in a S4B Online environment, others in a hybrid scenario.

 

Microsoft Teams

Microsoft has announced that Skype for Business Online will be replaced by Microsoft Teams this year. But there is little to no information about Teams and it’s compatiblity with the UCWA API.  I have done a few tests with the UCWA API and Microsoft Teams and I have concluded that the UCWA API is the same for Skype for Business and for Microsoft Teams. The API uses the ‘online.lync.com’ URLs, which Microsoft Teams also supports. So these steps can also be used for a Microsoft Teams environment.

Questions about this script or the UCWA API in the general? Feel free to reach out to me through the links in my bio with any questions or remarks.

Happy scripting!