Introduction to the Unified Communications Managed API 3.0

Hands-On Lab Introduction to the Unified Communications Managed API 3.0

Lab version: 1.0

Last updated: 1/19/2018 CONTENTS Overview

1. Lab Time: 45 Minutes 2. Lab Folder: C:\%UC14TrainingKit%\Labs\6\Source\Before

3. The After folder contains the completed lab exercises.

4. Lab Overview: The Unified Communications Managed API 3.0 SDK provides a managed API for developing server-side communications solutions for Microsoft Lync Server 2010 such as personal virtual assistants, automatic call distributors, and communications-enabled business processes. 5. Users can interact with these applications by placing a call to them via the PSTN, or by starting an audio or instant message conversation in Microsoft Lync with the contact associated with the application. 6. The lab solution you will build will use the UCMA 3.0 SDK to demonstrate the following. How to provision an application using the Lync Server PowerShell cmdlets.

How to provision an application endpoint using the Lync Server PowerShell cmdlets.

How to publish an application endpoint’s presence.

How to register for and handle an incoming audio conversation.

How to subscribe to the presence of a user and process presence notification event s when their state changes.

How to check a user’s availability.

How to transfer an audio conversation to another user.

System Requirements 1. You must have the following items to complete this lab: Microsoft Visual Studio 2010

Unified Communications Managed API 3.0 SDK

The port assigned for your use in the UC 14 Metro lab. Microsoft Lync Server 2010 will be configured to listen for your UCMA application on this port. Exercise 1: Provision an Application Endpoint and Publish its Presence

Task 1 – Create a New Trusted Application 2. In this task, you will create a new trusted UCMA application using Microsoft Lync Server 2010 PowerShell cmdlets. 3. Launch the Lync Server Management Shell from Start >> Administrative Tools >> Lync Server Management Shell. 4. Run the following command to create a new UCMA application, make sure to replace the values in < … > with the correct values for the parameters. 4.a.i. PowerShell 4.a.ii. New-CSTrustedApplication –ApplicationId 4.a.iii. -TrustedApplicationPoolFqdn -Port 4.b. ApplicationId: “LabApp” + the value of LocalSIPPort, e.g. LabApp10600. 4.b.i. If you are performing this exercise in your own development environment, LocalSIPPort represents an available port that Microsoft Lync Server 2010 will listen on for the new UCMA application. 4.c. TrustedApplicationPoolFqdn: the fully qualified domain name of the application server in the Microsoft Lync Server 2010 topology that this application will be provisioned on, e.g. ts.fabrikam.com. 4.d. Port: the port assigned for your use in the lab. 4.d.i.

5. Record the value displayed for the ApplicationId property. 6. As prompted, run the Enable-CsTopology PowerShell command to commit the changes. 6.a. PowerShell 6.b. Enable-CsTopology

7. Run the following command to verify that the UCMA application was created successfully, and to retrieve its details. 7.a. The value for is the value of TrustedApplicationPoolFqdn + “/” + the value of ApplicationName, e.g. ts.fabrikam.com/urn:application:labapp10600 7.a.i. PowerShell 7.a.ii. Get-CSTrustedApplication –Identity

Task 2 – Create a New Trusted Application Endpoint 1. In this task, you will create a UCMA application endpoint using the Microsoft Lync Server 2010 PowerShell cmdlets. 2. Run the following command to create a new trusted UCMA application endpoint, make sure to replace the values in < … > with the correct values for the parameters. 2.a.i. PowerShell 2.a.ii. New-CSTrustedApplicationEndpoint –ApplicationId 2.a.iii. -TrustedApplicationPoolFqdn 2.a.iv. -SipAddress 2.a.v. -DisplayName 1.a. ApplicationId: The Id of the UCMA application recorded in the previous task, e.g. urn:application:labapp10600 1.b. TrustedApplicationPoolFqdn: The same value as in the previous task, e.g. ts.fabrikam.com. 1.c. SipAddress: The SIP URI of the Microsoft Lync contact associated with the application endpoint. 1.c.i. In the UC 14 Metro Lab, use the following naming convention: “sip:LabContact” + the value of LocalSIPPort + “@fabrikam.com”, e.g. sip:[email protected] 1.d. DisplayName: A friendly display name for the Microsoft Lync contact associated with the application endpoint, e.g. Lab Contact 10600.

2.a.vi.

3. Run the following command to verify that the application endpoint was created successfully and retrieve its details, where Identity is the SIP address of your lab contact, e.g. : sip:[email protected]. 3.a.i. PowerShell 3.a.ii. Get-CSTrustedApplicationEndpoint –Identity

3.a.iii. Task 3 – Open the Visual Studio Solution 1. In this task, you will open the project and configure it to run with your parameter values. 2. Navigate to Start >> All Programs >> Microsoft Visual Studio 2010. 1. Click on the Microsoft Visual Studio 2010 icon to start Visual Studio 2010. 2. Select File >> Open Project. 3. Navigate to the folder C:\%UC14TrainingKit%\Labs\6\Source\Before. 3. Open the IntroductionToUCMA solution. 4. In Solution Explorer, right-click the ProvisionedPublishAlwaysOnline project and select Set as Startup Project. 5. In Solution Explorer, open the App.config file. 6. Change the value of ApplicationId to the value from Task 1, e.g.: urn:application:LabApp10600. 7. Change the value of ApplicationName to the value from Task 1, e.g.: LabApp10600. 8. Select View >> Task List and select Comments from the menu.

Task 4 – Publish the Presence of the Application Endpoint 1. In this task, you will configure the UCMA application created in the previous tasks to appear as a Microsoft Lync contact whose presence always appears as Online. 2. In the Task List, navigate to TODO: 6.1.1. 3. Add the following code after the TODO: 6.1.1 comment. Access your application’s settings and create an instance of CollaborationPlatform for connection management, message dispatching, and other services that the Microsoft Lync Server 2010 provides to your endpoint. 3.a.i. C# 3.a.ii. var settings = new ProvisionedApplicationPlatformSettings( 3.a.iii. _applicationName, _applicationId); 3.a.iv. _collabPlatform = new CollaborationPlatform(settings);

4. Navigate to TODO: 6.1.2. 5. Add the following code after the TODO: 6.1.2 comment. Create an event handler to determine the SIP URI of the contact associated with the application. 5.a.i. C# _collabPlatform.RegisterForApplicationEndpointSettings(this.Platform_Ap plicationEndpointOwnerDiscovered);

6. Navigate to TODO: 6.1.3. 7. Add the following code after the TODO: 6.1.3 comment. Start the CollaborationPlatform instance and specify a delegate to be called when startup completes. 7.a.i. C# 7.a.ii. Console.WriteLine("Starting the platform."); 7.a.iii. _collabPlatform.BeginStartup(PlatformStartupCompleted, null);

8. Navigate to TODO: 6.1.4. 9. Add the following code after the TODO: 6.1.4 comment. Display the SIP URI of any contacts associated with the application endpoint as they are discovered. 9.a.i. C# 9.a.ii. Console.WriteLine("Contact discovered: {0}", 9.a.iii. e.ApplicationEndpointSettings.OwnerUri); 10. Navigate to TODO: 6.1.5. 11. Add the following code after the TODO: 6.1.5 comment. Initialize and register the application endpoint. 11.a.i. C# 11.a.ii. var settings = e.ApplicationEndpointSettings; 11.a.iii. settings.AutomaticPresencePublicationEnabled = true; 11.a.iv. settings.Presence.PresentityType = "automaton"; 11.a.v. settings.Presence.Description = "AlwaysOnlineBot"; 11.a.vi. 11.a.vii. _applicationEndpoint = new ApplicationEndpoint(_collabPlatform, settings); 12. Navigate to TODO: 6.1.6. 13. Add the following code after the TODO: 6.1.6 comment. Establish the endpoint. 13.a.i. C# 13.a.ii. _applicationEndpoint.EndEstablish(result); 13.a.iii. Console.WriteLine("The application endpoint owned by URI: {0} is now established and registered.", _applicationEndpoint.OwnerUri); 14. Go to Debug >> Start Without Debugging or use the shortcut key [CTRL]+[F5] to start the application. 15. Press the Enter key.

16. Press Enter to shut down the console application. 17. Open Microsoft Lync. 18. Type the SIP URI of the application contact into the search box, the contact should appear in the search results. 19. Verify that the presence of the contact appears as Available. 20. Add the contact to your Microsoft Lync contact list.

20.a. Exercise 2: Call Control and Presence Events

Task 1 – Open the Visual Studio Solution 1. In this task, you will open the project and configure it to run with your parameter values. 1. Navigate to Start >> All Programs >> Microsoft Visual Studio 2010. 9. Click on the Microsoft Visual Studio 2010 icon to start Visual Studio 2010. 10. Select File >> Open Project. 11. Navigate to the folder C:\%UC14TrainingKit%\Labs\6\Source\Before. 12. Open the IntroductionToUCMA solution. 13. In Solution Explorer, right-click the CallControlandPresenceEvents project and select Set as Startup Project. 14. In Solution Explorer, open the App.config file. 15. Change the ApplicationId to the application id assigned to you, e.g. (urn:application:LabApp10600). 16. Change the ApplicationName to the application name assigned to you, e.g. (LabApp10600).. 17. Change the TrustedContactUri to the trusted contact uri assigned to you, e.g. (sip:[email protected]). 18. Change the PrimaryLabUserId and SecondaryLabUserId values to your primary and secondary lab accounts. 19. Select View >> Task List and select Comments from the menu. Task 2 – Register for an Incoming Call on the Application Endpoint 2. In this task, you will register the application endpoint to receive calls. 1. In the Task List, navigate to TODO: 6.2.1. 3. Add the following code after the TODO: 6.2.1 comment. Register for an incoming AudioVideoCall. 3.a.i. C# 3.a.ii. _applicationEndpoint.RegisterForIncomingCall(AudioVideoCallReceived); 4. Navigate to TODO: 6.2.2. 5. Add the following code after the TODO: 6.2.2 comment. Get the incoming call and add a handler for call state changes. 5.a.i. C# 5.a.ii. Console.WriteLine("\nIncoming audio call from {0}.", 5.a.iii. e.RemoteParticipant.Uri); 5.a.iv. _initialAVCall = e.Call; 5.a.v. _initialAVCall.StateChanged += 5.a.vi. new EventHandler( 5.a.vii. AudioVideoCall_StateChanged); 6. Navigate to TODO: 6.2.3. 7. Add the following code after the TODO: 6.2.3 comment. Accept the incoming call. 7.a.i. C# 7.a.ii. _initialAVCall.EndAccept(result); 8. Go to Debug >> Start Without Debugging or use the shortcut key [CTRL]+[F5] to start the application. 9. Check that the console displays messages indicating that the application endpoint has been registered for incoming calls.

9.a.i.

10. Switch to Microsoft Lync and search for your provisioned lab contact, e.g. [email protected]. 11. Click the Call button to place an audio call to the provisioned lab contact. 12. Check the console for a message indicating that the application is receiving an incoming call and that the CallStateChanged event fires as the state changes from Incoming to Establishing and then from Establishing to Established.

12.a.i. 13. End the call by clicking the End Call button. 14. Check that the console displays CallStateChanged events as the call’s state changes from Established to Terminating and then from Terminating to Terminated. 14.a.i. 15. Press Enter and close the console application. Task 3 – Subscribe to Presence and Handle Presence Notification Events. 16. In this task, you will subscribe to presence notification events from the secondary lab user. 1. Navigate to TODO: 6.2.4. 17. Add the following code after the TODO: 6.2.4 comment. Subscribe to presence notifications for the secondary lab user. 17.a.i. C# 17.a.ii. SubscribeToPresenceOfSecondaryLabUser(); 18. Navigate to TODO: 6.2.5. 19. Add the following code after the TODO: 6.2.5 comment. Create a list of contacts to subscribe to presence notifications for. 19.a.i. C# 19.a.ii. var subscriptionTargets = new List(); 19.a.iii. subscriptionTargets.Add(new RemotePresentitySubscriptionTarget(_secondaryLabUserId)); 19.a.iv. 19.a.v. _remotePresenceView = new RemotePresenceView( 19.a.vi. _applicationEndpoint, 19.a.vii. new RemotePresenceViewSettings() { SubscriptionMode = RemotePresenceViewSubscriptionMode.Persistent }); 19.a.viii. 19.a.ix. // Wire up NotificationReceived before adding targets 19.a.x. _remotePresenceView.PresenceNotificationReceived += new EventHandler(RemotePresenceVie w_NotificationReceived); 19.a.xi. 19.a.xii. // Immediately fires NotificationReceived with current presence of targets _remotePresenceView.StartSubscribingToPresentities(subscriptionTargets); 20. Navigate to TODO: 6.2.6. 21. Add the following code after the TODO: 6.2.6 comment. Process the presence notifications by determining the contact that each notification is referring to, and then checking if that contact is online. If the user is online, remove the notification event handler to avoid an infinite loop. 21.a.i. C# 21.a.ii. foreach (var notification in e.Notifications) 21.a.iii. { 21.a.iv. // Verify that we are receiving a presence notification for the secondary lab user 21.a.v. if (notification.Uri.Equals(_secondaryLabUserId, StringComparison.InvariantCultureIgnoreCase)) 21.a.vi. { 21.a.vii. if (IsUserAvailable(notification)) 21.a.viii. { 21.a.ix. // Unsubscribe from notifications 21.a.x. _remotePresenceView.StartUnsubscribingToPresentities( 21.a.xi. new List() { _secondaryLabUserId } ); _remotePresenceView.PresenceNotificationReceived -= new EventHandler(RemotePresenceVie w_NotificationReceived); 21.a.xii. 21.a.xiii. Console.WriteLine("\n{0} is now available.", _secondaryLabUserId); 21.a.xiv. 21.a.xv. // Present call transfer options to the user 21.a.xvi. PresentCallTransferOptionsToUser(); 21.a.xvii. } 21.a.xviii. break; 21.a.xix. } 21.a.xx. } 22. Navigate to TODO: 6.2.7. 23. Add the following code after the TODO: 6.2.7 comment. Check if the secondary lab user is online and available. 23.a.i. C# 23.a.ii. userIsOnline = notification.AggregatedPresenceState.Availability == PresenceAvailability.Online; 24. Switch to the secondary lab user’s session and open Microsoft Lync. 25. Set the secondary lab user’s status to Busy. 26. Switch back to the primary lab user’s session. 27. Go to Debug >> Start Without Debugging or use the shortcut key [CTRL]+[F5] to start the application. 28. Place an audio call to the application contact. 29. Check the console for a message indicating that it has subscribed to presence notification events for the secondary lab user.

29.a.i. 30. Go to the secondary lab user’s session and set the status to Available. 31. Check the console for a message indicating the change in the secondary lab user’s presence.

31.a.i. 32. Press Enter and close the console application. Task 4 – Perform an Unattended Call Transfer. 33. In this task, you will perform an unattended call transfer to the secondary lab user. 1. Navigate to TODO: 6.2.8. 34. Add the following code after the TODO: 6.2.8 comment. Present the user with the options for transferring a call. 34.a.i. C# 34.a.ii. bool valid = false; 34.a.iii. var transferAction = new ConsoleKey(); 34.a.iv. ConsoleKeyInfo cki = new ConsoleKeyInfo(); 34.a.v. while (!_selectedCallTransferAction) 34.a.vi. { 34.a.vii. Console.WriteLine("\nSelect a call transfer option to test:"); 34.a.viii. Console.WriteLine("1: Unattended call transfer"); 34.a.ix. Console.WriteLine("2: Attended call transfer with impersonation"); 34.a.x. 34.a.xi. while (!valid) 34.a.xii. { 34.a.xiii. cki = Console.ReadKey(true); 34.a.xiv. if (cki.Key.Equals(ConsoleKey.D1) 34.a.xv. || cki.Key.Equals(ConsoleKey.D2)) 34.a.xvi. { 34.a.xvii. valid = true; 34.a.xviii. _selectedCallTransferAction = valid; 34.a.xix. transferAction = cki.Key; 34.a.xx. } 34.a.xxi. } } 34.a.xxii. switch (transferAction) 34.a.xxiii. { 34.a.xxiv. case ConsoleKey.D1: 34.a.xxv. TransferCallUnattended(); 34.a.xxvi. break; 34.a.xxvii. case ConsoleKey.D2: 34.a.xxviii. TransferCallAttendedWithImpersonation(); 34.a.xxix. break; 34.a.xxx. }; 35. Navigate to TODO: 6.2.9. 36. Add the following code after the TODO: 6.2.9 comment. Begin the call transfer to the secondary lab user and provide a callback function. 36.a.i. C# 36.a.ii. _initialAVCall.BeginTransfer( 36.a.iii. targetUri: _secondaryLabUserId, 36.a.iv. callTransferOptions: 36.a.v. new CallTransferOptions(CallTransferType.Unattended), 36.a.vi. userCallback: result => 36.a.vii. { 36.a.viii. try 36.a.ix. { 36.a.x. _initialAVCall.EndTransfer(result); 36.a.xi. } 36.a.xii. catch (RealTimeException e) 36.a.xiii. { 36.a.xiv. Console.WriteLine("Error transferring call: {0}", 36.a.xv. e.Message); 36.a.xvi. } 36.a.xvii. }, 36.a.xviii. state: null); 37. Go to the secondary lab user’s session and set the status to Busy. 38. Go back to the primary lab user’s session. 39. Press [CTRL]+[F5] to start the application. 40. Place an audio call to the application contact. 41. Go to the secondary lab user’s session and set the status to Available. 42. Go to the console and press 1 to perform an unattended call transfer. 43. Check the console for a message indicating that the original call has been transferred and then terminated. 43.a.i. 44. Switch to the secondary lab user’s session and answer the call. 45. Switch back to the primary lab user’s session. 46. Check the console for a message indicating that the call has been transferred to the secondary lab user. 47. Note that with an unattended transfer, the original call is automatically transferred and terminated.

47.a.i.

48. End the call 49. Press Enter and close the application. Task 5 – Perform an Attended Call Transfer with Impersonation. 50. In this task, you will perform an attended call transfer to the secondary lab user. 1. Navigate to TODO: 6.2.10. 20. Add the following code after the TODO: 6.2.10 comment. Set the conversation to impersonate the primary lab user. 50.a.i. C# 50.a.ii. conversation.Impersonate(uri: _primaryLabUserId, 50.a.iii. phoneUri: null, 50.a.iv. displayName: null); 21. Navigate to TODO: 6.2.11. 22. Add the following code after the TODO: 6.2.11 comment. Establish the call to the secondary lab user by providing an asynchronous callback. 50.a.v. C# 50.a.vi. audioVideoCall.EndEstablish(result1); 23. Navigate to TODO: 6.2.12. 24. Add the following code after the TODO: 6.2.12 comment. Begin the transfer by providing the call object, the call options, and the callback method. 50.a.vii. C# 50.a.viii. _initialAVCall.BeginTransfer( 50.a.ix. callToReplace: audioVideoCall, 50.a.x. callTransferOptions: new CallTransferOptions(CallTransferType.Attended), 50.a.xi. userCallback: result => 50.a.xii. { 50.a.xiii. try 50.a.xiv. { 50.a.xv. _initialAVCall.EndTransfer(result); 50.a.xvi. } 50.a.xvii. catch (OperationFailureException ofe) 50.a.xviii. { 50.a.xix. Console.WriteLine("The recipient declined or did not answer the call: {0}", ofe.Message); 50.a.xx. 50.a.xxi. } 50.a.xxii. catch (RealTimeException e) 50.a.xxiii. { 50.a.xxiv. Console.WriteLine("Error transferring call: {0}", e.Message); 50.a.xxv. } 50.a.xxvi. }, 50.a.xxvii. state: null); 51. Go to the secondary lab user’s session and set the status to Busy. 52. Go back to the primary lab user’s session. 53. Press [CTRL]+[F5] to start the application. 54. Place an audio call to the application contact. 55. Go to the secondary lab user’s session and set the status to Available. 25. Press 2 to perform an attended call transfer. 55.a.i.

56. Switch to the secondary lab user’s session and answer the call. 57. Switch back to the primary lab user’s session. 58. Check the console for messages indicating that the original call is only terminated after the transfer recipient picks up the transferred call.

58.a.i.

26. End the call. 27. Press Enter and close the application. Summary

In this lab, you learned how to provision a UCMA application and a Microsoft Lync contact as an endpoint for the application and how to publish that contact’s presence as AlwaysOnline so that the contact’s presence always appears as online when users interact with it in Microsoft Lync. Additionally, you learned you to configure a UCMA application to handle incoming calls, subscribe to a user’s presence and perform call transfers.