Introduction to the Unified Communications Managed API 3.0

mountainromeInternet and Web Development

Oct 31, 2013 (3 years and 10 months ago)

236 views





Hands
-
On Lab

Introduction to the Unified Communications
Managed API 3.0



Lab version:



1.0

Last updated:


11/1/2013










CONTENTS

OVERVIEW
................................
................................
................................
................................
........
3

System Requirements

3

EXERCISE 1: PROVISIO
N AN APPLICATION END
POINT AND PUBLISH IT
S PRESENCE

................
4

Task 1


Create a New Trusted Application

................................
................................
...................
4

Task 2


Create a New Trusted Application Endpoint

................................
................................
.....
5

Task 3


Open the Visual Studio Solution

................................
................................
......................
7

Task 4


Publish the Presence of the Application Endpoint

................................
.............................
7

EXERCISE 2: CALL CON
TROL AND
PRESENCE EVENTS

................................
................................
9

Task 1


Open the Visual Studio Solution

................................
................................
....................

10

Task 2


Register for an Incoming Call on the Application Endpoint

................................
..............

10

Ta
sk 3


Subscribe to Presence and Handle Presence Notification Events.
................................
.....

12

Task 4


Perform an Unattended Call Transfer.
................................
................................
............

14

Task 5


Perform an Attended Call Transfer with Impersonation.

................................
.................

16

SUMMARY

................................
................................
................................
................................
......

18



Overview

Lab Time:

4
5 Minutes

Lab Folder:

C:
\
%
UC14TrainingKit
%
\
Labs
\
6
\
Source
\
Before

The
After

folder contains the completed lab exercises.

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.

Users can interact with these applications by placing a call to them via the PSTN, or by starting an audio
or instant message conversatio
n in Microsoft
Lync

with the contact associated with the application.


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 pres
ence 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

You must have the following items to complete this lab:



Microsoft Visual Studio 2010



Unified Communications Managed API 3.0 SDK



T
he 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

it
s

Presence


Task
1



Create a New

Trusted

Application

In this task, you will create a
new
trusted
UCMA

application using
Microsoft Lync Server 2010

PowerShell

cmdlets
.

1.

Launch the
Lync

Server
Management Shell
from
Start >> Administrative Tools >>
Lync
Server Management Shell
.

2.

Run the following command
to create a new UCMA app
lication, m
ake sure to replace the
values in
<


>

with the correct values for the parameters.

PowerShell

New
-
CS
Trusted
Application

ApplicationId
<ApplicationId>

-
TrustedApplication
Pool
Fqdn <
TrustedApplicationPoolFqdn
>
-
Port <
Port
>

a.

ApplicationId
: “
LabApp


+ the value of
LocalSIPPort
, e.g.
LabApp10600
.

i.

If you are performing this exercise in your own development environment,
LocalSIPPort

represents an available po
rt that
Microsoft Lync Server 2010

will
listen on for the new UCMA application.

b.

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
.

c.

Port
:

the port assigned for your use in the lab.


3.

Record the value displayed
for the
ApplicationId

property
.

4.

As prompted, run the
Enable
-
CsTopology

PowerShell command to commit the changes.

PowerShell

Enable
-
CsTopology


5.

Run the following command to verify that the
UCMA
application was created successfully
,

and
to
retrieve its details
.


The value for
<
Identity
>

is the
value of
TrustedApplicationPool
Fqdn
+

/

+ the value of

ApplicationName
,
e.g.
ts.f
abrik
am.com/urn:application:labapp106
00

PowerShell

Get
-
CSTrusted
Application

Identity
<Identity
>



Task
2



Create a New

Trusted
Application Endpoint

In this task, you will
create a UCMA application endpoint using
the
Microsoft Lync Server 2010

PowerShell

cmdlets.

1.

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.

P
owerShell

New
-
CS
Trusted
ApplicationEndpoint

ApplicationId
<ApplicationId
>

-
TrustedApplicationPool
Fqdn

<
TrustedApplicationPool
Fqdn>

-
SipAddress <SipAddress>

-
DisplayName <DisplayName>

a.

ApplicationId
:

The Id

of the UCMA applicatio
n recorded

in the previous task, e.g.
urn:application:labapp10600


b.

TrustedApplication
PoolFqdn
:

The same value as in the previous task, e.g.
ts.fabrikam.com
.

c.

SipAddress:

The SIP URI of the Microsoft
Lync

contact associated with the
application endpoint.

i.

In the UC
14 Metro Lab, use the following naming convention:
“sip:LabContact”
+ the value of
LocalSIPPort

+
“@fabrikam.com”
,
e.g.
sip:LabContact10600@fabrikam.com

d.

DisplayName
: A friendly display name for the Microsoft
Lync

contact associated with
the application endpoint, e.g.
Lab Contact 10600
.


2.

Run
the following command to verify that the application en
dpoint was created succes
sfully
and retrieve its details, where
Identity

is the SIP address of your lab contact, e.g. :
sip:LabContact10600@fabrikam.com
.

PowerShell

Get
-
CS
Trusted
ApplicationEndpoint

Identity <
Identity
>



Task 3


Open the Visual Studio Solution

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
.

2.

Click on the
Microsoft Visual Studio 2010

icon to start Visual Studio 2010.

3.

Select
File >> Open Project
.

4.

Navigate to the folder
C:
\
%UC14TrainingKit%
\
Labs
\
6
\
Source
\
Before
.

5.

Open the
IntroductionToUCMA

solution.

6.

In
Solution Explorer
, right
-
click the
ProvisionedPublishAlwaysOnline

project and select
Set
as Startup Project
.

7.

In
Solution Explorer
, open the
App.config

file.

8.

Change the

value of

ApplicationId

to the
value
from Task 1, e.g
.
:

urn:application:LabApp10600
.

9.

C
hange

the
value of
ApplicationName

to the
value from Task 1, e.g.:
LabApp10600
.

10.

Select
View >> Task List

and select
Comments

from the menu.


Task 4



Publish the Presence of the Application Endpoint

In this ta
sk, you will configure the UCMA application created in the previous tasks to appear as a
Microsoft
Lync

contact
whose presence always appears as O
nline.

1.

In the
Task List
, n
avigate to
TODO: 6.1.1
.

2.

Add the following code after the
TODO: 6.1.1

comment.

Acces
s 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.

C#

var

settings = new ProvisionedApplicationPlat
formSettings(


_applicationName,
_applicationId);

_collabPlatform = new CollaborationPlatform(settings);


3.

Navigate to
TODO: 6.1.2
.

4.

Add the following code after the
TODO: 6.1.2

comment.

Create an event handler to
determine the SIP
URI

of the contact ass
ociated with the application.

C#

_collabPlatform.RegisterForApplicationEndpointSettings(this.Platform_App
licationEndpointOwnerDiscovered);


5.

Navigate to
TODO: 6.1.3
.

6.

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.

C#

Console.WriteLine("Starting the platform.");


_collabPlatform.BeginStartup(PlatformStartupCompleted, null);


7.

Navigate to
TODO: 6.1.4
.

8.

Add the following code after the
TODO: 6.1.
4

comment.

Display the SIP URI of any contacts
associated with the application e
ndpoint as they are discovered.

C#

Console.WriteLine(
"Contact discovered: {0}",


e.ApplicationEndpointSettings.OwnerUri);

9.

Navigate to
TODO: 6.1.5
.

10.

Add the following code

after the
TODO: 6.1.5

comment.


Initialize and register the
application endpoint.

C#

var settings = e.ApplicationEndpointSettings;

settings.AutomaticPresencePublicationEnabled = true;

setti
ngs.Presence.PresentityType = "a
utomaton";

settings.Presence.Descr
iption = "A
lwaysOnline
Bot";


_applicationEndpoint = new ApplicationEndpoint(_collabPlatform,
settings);

11.

Navigate to
TODO: 6.1.6
.

12.

Add the following code after the
TODO: 6.1.6

comment.

Establish the endpoint
.

C#

_applicationEndpoint.EndEstablish(result);


Console.WriteLine("The application endpoint owned by URI: {0} is
now established and registered.", _applicationEndpoint.OwnerUri);


13.

Go to
Debug >> Start Without Debugging

or use the shortcut key
[CTRL]+[F5]

to start the
application.

14.

Press the
Enter

key.



15.

Press
Enter

to shut down the console application.

16.

Open
Microsoft
Lync
.

17.

Type the SIP
URI

of the application contact into the search
box, the contact should appear in
the search results.

18.

Verify that the presence of the contact appears as
Available
.

19.

Add the contact to your Microsoft
Lync

contact list.



Exercise 2: Call Control and Presence
Events

Task 1


Open the Visual Studio Solution

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
.

2.

Click on the
Microsoft Visual Studio 2010

icon to start Visual Studio 2010.

3.

Select
File >> Open Project
.

4.

Navigate to the folder
C:
\
%UC14TrainingKit%
\
Labs
\
6
\
Source
\
Before
.

5.

Open the
IntroductionToUCMA

solution.

6.

In
Solution Explorer
, right
-
click the
CallControlandPresenceEvents

project and select
Set as
Startup Project
.

7.

In
Solution Explorer
, open the
App.config

file.

8.

Change the
ApplicationId

to the
a
pplication

i
d

assigned to you, e.g.

(urn:application:LabApp10600).

9.

Change the
ApplicationName

to the

application name

assigned to you
, e.g.
(LabApp10600)
..

10.

Change the
TrustedContactUri

to the
trusted contact uri

assigned to you, e.g.

(
sip:LabContact10600@fabrikam.com
).

11.

Change the
PrimaryLabU
serId

and
SecondaryLabUserId

values to your

primary and
secondary lab

accounts.

12.

Select
View >> Task List

and select
Comments

from the menu.

Task 2


Register for an Incoming Call on the Application Endpoint

In this task, you will register the application e
ndpoint to receive calls.

1.

In the
Task List
, navigate to
TODO: 6.2.1
.

2.

Add the following code after the
TODO: 6.2.1

comment.

Register for an incoming
AudioVideoCall
.

C#

_applicationEndpoint.RegisterForIncomingCall<AudioVideoCall>(AudioVideoC
allReceived);

3.

Navigate to
TODO: 6.2.2
.

4.

Add the following code after the
TODO: 6.2.2

comment.

Get the incoming call and add a
handler for
call
state changes.

C#

Console.WriteLine("
\
n
Incoming audio call from {0}.",


e.RemoteParticipant.Uri);

_initialAVCall = e.Call
;

_initialAVCall.StateChanged +=


new

EventHandler<CallStateChangedEventArgs>(


AudioVideoCall_StateChanged);

5.

Navigate to
TODO: 6.2.3
.

6.

Add the following code after the
TODO: 6.2.3

comment.

Accept the incoming call.

C#

_initialAVCall.EndAccept(result);

7.

Go to
Debug >> Start Without Debugging

or use the shortcut key
[CTRL]+[F5]

to start the
application.

8.

Check that the console displays messages indicating that the application endpoint has been
registered for incoming calls.


9.

Switch to
Microsoft
Lync

and search for you
r

provisioned lab contact, e.g.
LabContact10600@fabrikam.com
.

10.

Click the
Call

button to place an audio call to the provisioned lab contact.

11.

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.

End the call by clicking

the
End

Call

button.

13.

Check that the console displays
CallStateChanged

events as the call’s state changes from
Established

to
Terminating

and then from
Terminating

to
Terminated
.


14.

Press
Enter

and close the console application.

Task 3


Subscribe to Presen
ce and Handle Presence Notification Events.

In this task, you will
subscribe to presence notification events from the secondary lab user.

1.

Navigate to
TODO: 6.2.4
.

2.

Add the following code after the
TODO: 6.2.4

comment.

Subscribe to presence notifications
fo
r the secondary lab user.

C#

SubscribeToPresenceOfSecondaryLabUser();

3.

Navigate to
TODO: 6.2.5
.

4.

Add the following code after the
TODO: 6.2.5

comment.

Create a list of contacts to
subscribe
to presence notifications
for.

C#

var subscriptionTargets = new
List<RemotePresentitySubscriptionTarget>();

subscriptionTargets.Add(new
RemotePresentitySubscriptionTarget(_secondaryLabUserId));


_remotePresenceView = new RemotePresenceView(


_applicationEndpoint,


new RemotePresenceViewSettings() { SubscriptionMo
de =
RemotePresenceViewSubscriptionMode.Persistent });


// Wire up NotificationReceived before adding targets

_remotePresenceView.
Presence
NotificationReceived +=

new
EventHandler<RemotePresentities
NotificationEventArgs>(RemotePresenceView
_NotificationRecei
ved);



// Immediately fires NotificationReceived with current presence of
targets

_remotePresenceView.StartSubscribingToPresentities(subscriptionTargets);

5.

Navigate to
TODO: 6.2.6
.

6.

Add the following code after the
TODO: 6.2.6

comment.

Process the p
resence notifications
by determining the c
ontact
that
each
notification is referring to, and then checking if that
contact is online
.
If the user is online, r
emove

the
notification event
handler to avoid an
infinite loop.

C#

foreach (var notification in e
.Notifications)

{


// Verify that we are receiving a presence notification for the
secondary lab user


if (notification.Uri.Equals(_secondaryLabUserId,
StringComparison.InvariantCultureIgnoreCase))


{



if (IsUserAvailable(notification))



{



// Unsubscribe from notifications



_remotePresenceView.StartUnsubscribingToPresentities(


new List<string>() { _secondaryLabUserId } );


_remotePresenceView.
Presence
NotificationReceived
-
=

new
EventHandler<RemotePresentities
NotificationEventArgs>(RemotePresenceView
_NotificationReceived);



Console.WriteLine("
\
n{0} is now available.",
_secondaryLabUserId);




// Present call transfer options to the user



PresentCallTransferOptionsToUser();


}


break;


}

}

7.

Navigate to
TODO: 6.2.7
.

8.

Add the following code after the
TODO: 6.2.7

comment.

Check if the secondary lab user is
online and available.

C#

userIsOnline = notification.AggregatedPresenceSt
ate.Availability ==
PresenceAvailability.Online;

9.

Switch to the secondary lab user’s session and open
Microsoft
Lync
.

10.

Set the secondary lab user’s status to
Busy
.

11.

Switch back to the primary lab user’s session.

12.

Go to
Debug >> Start Without Debugging

or use t
he shortcut key
[CTRL]+[F5]

to start the
application.

13.

Place an audio call to the application contact.

14.

Check the console for a message indicating that it has subscribed to presence notification
events for the secondary lab user.


15.

Go to the secondary lab u
ser’s session and set the status to
Available
.

16.

Check the console for a message indicating the change in the secondary lab user’s presence.


17.

Press
Enter

and close the console application.

Task 4


Perform

an

Unattended Call Transfer.

In this task, you will
perform an unattended call transfer to the secondary lab user.

1.

Navigate to
TODO: 6.2.8
.

2.

Add the following code after the
TODO: 6.2.8

comment.

Present the user with
the options
for transferring a call.


C#

bool valid = false;

var
transferAction = new ConsoleKey();

ConsoleKeyInfo cki = new ConsoleKeyInfo();

while (!_selectedCallTransferAction)

{


Console.WriteLine("
\
nSelect a call transfer option to test:");


Console.WriteLine("1: Unattended call transfer");


Conso
le.WriteLine(
"2: Attended call transfer with
impersonation");



while (!valid)


{


cki = Console.ReadKey(true);


if (cki.Key.Equals(ConsoleKey.D1)


||

cki.Key.Equals(ConsoleKey.D2))


{



valid = true;


_selectedCallTransferAction = valid;


transferAction = cki.Key;


}


}

}


switch (transferAction)

{


case ConsoleKey.D1:


TransferCallUnattended();


break;


case
ConsoleKey.D2:


TransferCallAttendedWithImpersonation();


break;

};

3.

Navigate to
TODO: 6.2.9
.

4.

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
.

C#

_
initialAVCall.BeginTransfer(


targetUri: _secondaryLabUserId,


callTransferOptions:


new CallTransferOptions(CallTransferType.Unattended),


userCallback: result =>


{


try


{


_initialAVCall.EndTransfer(result);


}


catch (RealTimeException e)


{


Console.WriteLine("Error transferring call: {0}",


e.Message);


}


},


state: null);

5.

Go to the secondary lab user’s session and set the status to
Busy
.

6.

Go back to the primary lab user’s session.

7.

Press
[CTRL]+[F5]

to start the application.

8.

Place an audio call to the application contact.

9.

Go to the secondary lab user’s session and set the sta
tus to
Available
.

10.

Go to the console and p
ress
1

to perform an unattended call transfer.

11.

Check the console for a message indicating that the original call has been transferred and
then terminated.


12.

Switch to the secondary lab user’s session and answer the
call.

13.

Switch back to the primary lab user’s session.

14.

Check the console for a message indicating that the call has been transferred to the
secondary lab user.

15.

Note that with an unattended transfer, the original call is automatically transferred and
terminat
ed.


16.

End the call

17.

Press
Enter

and close the application.

Task 5


Perform an Attended Call Transfer with Impersonation.

In this task, you will
perform an attended call transfer to the secondary lab user.

1.

Navigate to
TODO:

6.2.10
.

2.

Add the following code after the
TODO: 6.2.10

comment.

Set the conversation to
impersonate the primary lab user.

C#

conversation.Impersonate(uri: _primaryLabUserId,


phoneUri: null,


displayName: null);

3.

Navigate to
TODO: 6.2.11
.

4.

Add the foll
owing code after the
TODO: 6.2.11

comment.

Establish the call to the secondary
lab user by providing an asynchronous callback.

C#

audioVideoCall.EndEstablish(result1);

5.

Navigate to
TODO: 6.2.12
.

6.

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.

C#

_initialAVCall.BeginTransfer(


callToReplace: audioVideoCall,


callTransferOptions:


new CallTransferOptions(CallTransferType.Attended),


use
rCallback: result =>


{


try


{


_initialAVCall.EndTransfer(result);


}


catch (OperationFailureException ofe)


{


Console.WriteLine("The recipient declined or did not
answer

the call: {0}", ofe.Message);




}


catch (RealTimeException e)


{


Console.WriteLine("Error transferring

call: {0}",



e.Message);


}


},


state: null);

7.

Go to the secondary lab user’s session and set the status to
Busy
.

8.

Go back to the primary lab user’s session.

9.

Press
[CTRL]+[F5]

to start the application.

10.

Place an audio call to the application
contact.

11.

Go to the secondary lab user’s session and set the status to
Available
.

12.

Press
2

to perform an attended call transfer.


13.

Switch to the secondary lab user’s session and answer the call.

14.

Switch back to the primary lab user’s session.

15.

Check the consol
e for messages indicating that
t
he original call is only terminated after the
transfer recipient picks up the transferred call.


16.

End the call.

17.

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 inter
act 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.