This is quite easy to do, just remember:

• Use a secure string for the password: $secure_string_pwd = convertto-securestring "password" -asplaintext -force
• Create and import the session: $session = New-PSSession -ConnectionUri "https://domain/OcsPowerShell" -Credential $cred

 A complete sample code can be found on this post: Creating a Powershell session under a different set of credentials.

This will allow you to run the OcsPowershell cmdlets under different credentials and be correctly identified by the Role Based Access Control.

The properties are hopefully straight forward:

-          Name: a unique identifier for your particular orbit range

-          Number range: The minimum and maximum value of the range you want to assign for orbits. The real questions you are asked here are:

•   How many calls do you expect simultaneously (this will decide of the length of the range)?
•   Where do you have available extension (this will help you decide of the first value)

-          FQDN of destination server:  the fully qualified domain name of the application service (Front End or Front Ends pool) that host call park service.

There are a set of options you cannot control via the Control Panel, for example the custom music on hold (what the parked user will hear), the timeout URI, the maximum pickup attempts and the call pickup threshold can only be defined via PowerShell.

If you want to take a more programmatic approach and want to use the Lync Server Management Shell, you also can:

1. Open the Shell or Import the Lync module to your PowerShell console.
   PS C:\> Import-Module Lync
2. Get the service identity that host Call Park Service (CPS)
   PS C:\> $serviceId = Get-CSService | ?{$_.Applications -like "*CPS*"}).ServiceId
3. Enable Call Park feature in voice policy:
   PS C:\> Set-CSVoicePolicy -Identity Global -EnableCallPark $true
4. Define a custom music on hold to be stream:
   PS C:\> Set-CSCallParkServiceMusicOnHoldFile -Service $serviceId -Content ( gc 'CpsMoh.wma' -ReadCount 0 -Encoding byte)
5. Define a custom CPS configuration:
   Set-CSCpsConfiguration -OnTimeoutURI sip:pool0_user1@vdomain.com -MaxCallPickupAttempts 1 -CallPickupTimeoutThreshold 00:00:59
6. Create a new call orbit range:
   New-CSCallParkOrbit -Identity $servicesId[0].ToString() -NumberRangeStart 700 -NumberRangeEnd 899 -CallParkServerFqdn poolfqdn.vdomain.com

At this point you users should start receiving the Call Park Server URI and they should have the option to park call displayed on their Lync client.

Lync Call Park lives on a front-end on your Lync deployment. Scenarios enabled by call park application are:

-          Call parking: a Lync user can “park” a call, effectively the caller will get connected with the call park application and hear a music while he his on hold. Upon parking the call, the application will return to the parker a number (called an orbit number). This number may be used to retrieve the parked call.

-          Call retrieving: to retrieve a call, one needs to have the orbit number of this call. Lync user can compose this orbit and they will be connected to the parked user.

-          Call ring back: if timers for parked user expire, the call will ring back the user who parked the call (aka the parker). Note that the forwarding settings will not be taken into account.

-          Park failback: if the call ring back is not answered, then the parked call is transferred to a defined destination.

Below is the (over) simplified process of parking and retrieving a call:

Figure 1: parking and retrieving a call

A sample scenario for call park application would be:

1.        User call Contoso Hospital
2.        Receptionist answer the call
3.        Receptionist park the call and page the doctor an orbit number
4.        The doctor enters the orbit number in any telephone and gets connected to the caller.
   
   

In the next post, I will dive into the configuration of the call park application.

Thanks for reading!
Ahmet

To support this kind of scenarios, the agent groups support to have their agents collection updated via a distribution list (from active directory), so as an administrator we just have to maintain an AD group.

By default, RGS, synchronization interval with AD is eight hours. This might not fit into all scenarios. If you need to have a shorter cycle time, there is still an option: creating a config file for OcsAppServerHost.exe.

Below is what you will want to insert into the config file (more details in the KB about this):

<?xml version="1.0" encoding="utf-8" ?>

<configuration>

   <appSettings>

      <add key="AdUpdateInterval" value="Number" />

   </appSettings>

</configuration>

Number needs to between 5 and 480 and it represents minutes J. Save the file as OcsAppServerHost.exe.config in the folder where the OcsAppServerHost.exe file is located.

Once you have this done, just restart RGS and you cycle time will be the one you entered in the config file.

If you are using OCS 2007 R2, there is a patch to make this work.

As for previous objects, let's start by looking at the properties of the workflow object:

• Parent <RgsIdentity>: The service where the workflow will be hosted.
• Name <String>: Unique name assigned to the workflow.
• PrimaryUri <Uri>: SIP address for the workflow, must begin with "sip:" prefix.
• Active <$true | $false>: If set to true, means that the workflow is active and available to accept phone calls.
• Anonymous <$true | $false>: If set to true, the identities of the agents will be masked (for incoming call). This also enable to make call on behalf of the workflow.
• BusinessHoursID <Nullable>: The ID of the HoursOfBusiness object defines the days of the week and times of the day that the workflow agents are available to answer calls.
• CustomMusicOnHoldFile <AudioFile>: Represents custom music to be played when callers are placed on hold. If not defined, the callers will hear the default music on hold.
• Description <String>: Description of the workflow, this is displayed in the Lync contact card.
• DisplayNumber <String>: Phone number for the workflow as displayed in Lync 2010, allow to be formatted as wanted.
• EnabledForFederation <$true | $false>: Indicates whether the workflow is available to federated users.
• HolidayAction <CallAction>: Action to be taken if the call is received on a holiday.
• HolidaySetIdList <RgsHolidaySet>: Represents days (RgsHoliday) when workflow agents are not available to answer calls.
• Language <String>: The language used to read workflow text-to-speech (TTS) prompts.
• LineUri <Uri>: Phone number for the workflow, must be prefixed with "tel:+".
• NonBusinessHoursAction <CallAction>: Action to be taken if a call is received outside the workflow business hours.
• TimeZone <String>: Time zone information used when determining holidays and business hours.

To set the workflow you can either use the Lync Management Shell or the web interface. Keep in mind that the web interface does not enable all features of the workflow but can be convenient to quickly create a workflow.

Let's have a quick try with the Response Group configuration tool:

Figure 1: Response Group Configuration Tool

• 1. Open the Response Group Configuration Tool (https://pool.fqdn.com/RGSConfig)
• 2. Click on Create to create a new hunt group
• 3. Enter values to set you workflow (primary uri, display name, queue, ...)
• 4. Click the deploy button
• 5. Now you response group should be up and running in two minutes maximum.

To get more control over our hunt group settings we will now go ahead and use the Lync Management Shell to create our workflow.

• 1. Open the Shell or Import the Lync module to your PowerShell console.
  PS C:\> Import-Module Lync
• 2. Get the service identity that will host your workflow
  PS C:\> $serviceId="service:"+(Get-CSService | ?{$_.Applications -like "*RGS*"}).ServiceId;
• 3. Create the new workflow with some default settings
  PS C:\> $w = New-CsRgsWorkflow -Name "My first workflow" -PrimaryUri "sip:first@vdomain.com" -Parent $serviceId
• 4. Enter a description (optional)
  PS C:\> $w.Description = "First workflow created"
• 5. Set the display number (optional)
  PS C:\> $w.DisplayNumber = "+41 12 345 67 89"
• 6. Set the line Uri (optional) - make sure your gateway is properly configured
  PS C:\> $w.LineUri = "tel:+41123456789"
• 7. Create a call action for the default action
  • 7.1. Get the queue identity (the queue name is "My First Queue"
    PS C:\> $q = Get-CsRgsQueue |? {$_.Name -Like "My First Queue"}
  • 7.2. Create a prompt to be played as the welcome message
    PS C:\> $prompt = New-CsRgsPrompt -TextToSpeechPrompt "Thank you for calling our Response Group, we are looking for an agent to answer you."
  • 7.3. Create the call action transferring to the queue
    PS C:\> $defaultAction = New-CSRgsCallAction -Prompt $prompt -Action "TransferToQueue" -QueueId $q.Identity
  • 7.4. Set the workflow default action to the call action
    PS C:\> $w.DefaultAction = $defaultAction
• 8. Activate the workflow
  PS C:\> $w.Active = $true
• 9. Save the workflow to the database
  PS C:\> Set-CsRgsWorkflow $w

At this point your workflow can be reached from the PSTN or from any voice enabled user in the enterprise.
I will be showing how to configure a workflow with hours of business and holidays. Keep Reading!

Let's start by looking at the properties of the queue object:

• Parent <RgsIdentity>: The service where the queue will be hosted.
• Name <String>: Unique name assigned to the queue.
• AgentGroupIdList <Collection>: The collection of AgentGroup (by identity) serving the queue.
• Description <String>: Description of the queue, for administrator use only (will never be displayed to callers or agents)
• OverflowAction <RgsCallAction>: Action to be taken when the overflow threshold is reached.
• OverflowCandidate <NewestCall | OldestCall>: Indicate whether the overflow action applies to the oldest call in the queue or to the newest call.
• OverflowThreshold <0-1000>: Amount of time (in seconds) before the overflow action is triggered. Keep in mind that this action will only be triggered when the AgentAlertTime cycle is over (more details about this later).
• TimeoutAction <RgsCallAction>: Action to be taken when the timeout threshold is reached.
• TimeoutThreshold <10 - 65535>: Amount of time (in seconds) before the timeout action is triggered. Keep in mind that, as for the overflow threshold) this action will only be triggered when the AgentAlertTime cycle is over.
• InMemory <SwitchParameter>: Using the InMemory flag will create an object reference without commiting the object to the database.

As for the AgentGroup there are two ways to create a new queue: via the Lync Server Control Panel or via the Lync Server Management Shell. I will, again, start with the Control Panel way. You will however notice that to you lose some granularity (to add a prompt you have to use the PowerShell Cmdlet) in your settings when using the Control Panel instead of the PowerShell cmdlets.

Figure 1: Creating a new queue

1.       Open the Lync Server Control Panel (https://pool.fqdn.com/CSCP/)

2.       Navigate to 'Response Groups' panel

3.       Click on the 'Queue' tab

4.       Click the New button to create a new agent group

5.       Select the site that will host the new agent group

6.       Enter value to configure your queue

• Enter a name
• Enter a description
• Select the agent group(s) served by the queue
• [optional]: Enable and configure the queue timeout
• [optional]: Enable and configure the queue overflow

7.       Commit the changes

Now let's create and configure a queue using the Lync Server Management Shell.

1.       Open the Shell or Import the Lync module to your PowerShell console.
           PS C:\> Import-Module Lync

2.       Get the service identity that will host your queue
           PS C:\> $serviceId="service:"+(Get-CSService | ?{$_.Applications -like "*RGS*"}).ServiceId;

3.       Create the new queue with some default settings
           PS C:\>$q = New-CsRgsQueue -Parent $serviceId -Name "My First Queue"

4.       Enter a description (optional)
           PS C:\>$q.Decription = "Contain all agents group working from 1pm to 6pm"

5.       Add an agent group to the queue

          a.       Get the agent group identity
                     PS C:\> $ag_id = (Get-CsRgsAgentGroup -Name "My First Agent Group ").Identity

           b.      Add it to the queue agent group list
                     PS C:\>$q.AgentGroupIDList.Add($ag_id)

6.       Configure a queue overflow of 10 calls applied to the oldest call, transferring the call to a Sip Uri after playing a prompt indicating the transfer.
           # Create the prompt
           PS C:\> $prompt = New-CsRgsPrompt -TextToSpeechPrompt "Your call is being transferred, please hold the line"
           # Create the call action
           PS C:\>$ca = New-CsRgsCallAction -Action TransferToUri  -Prompt $prompt -Uri "sip:ahmet@vdomain.com"
           # Configure the queue
           PS C:\> $q.OverflowAction = $ca
           PS C:\> $q.OverflowCandidate = "OldestCall"
           PS C:\> $q.OverflowThreshold = 10

7.       Configure a queue timeout of 5 minutes, transferring the call to another queue after playing an informative message
           # Create the prompt
           PS C:\> $prompt = New-CsRgsPrompt -TextToSpeechPrompt "Your call is being transferred, please hold the line"
           # Get the transfer target queue identity
           PS C:\>$ttq = (Get-CsRgsQueue -Name "Timeout Transfer Queue").Identity
           # Create the call action
           PS C:\>$ca = New-CsRgsCallAction -Action TransferToQueue -Prompt $prompt -QueueID $ttq
           # Configure the queue
           PS C:\>$q.TimeoutAction = $ca
           PS C:\>$q.TimeoutThreshold = (5*60)

8.       Save the queue to the database
          PS C:\>Set-CsRgsQueue $q

As previously stated, if you have set an agent alert time on your agent group object, the queue timeout will not happen until an agent alert time cycle is completed if agents are available. What does this mean? Let's say you have an agent group with an agent alert time of 120 seconds and a queue timeout of 60 seconds. The action for the queue timeout will only be triggered after 120 seconds if an agent is eligible for the call (aka display the incoming call toast). If no agent is eligible for the call, the timeout will be triggered after 60 seconds.

Our journey to create a response group is nearly over: we now have agents, an agent group and a queue. The last piece missing is a workflow object. Keep reading!

• Action <Enumerator >: Action to be taken.
  • Terminate: will terminate the call (hang up).
  • TransferToQueue: call will be transferred to selected queue.
  • TransferToQuestion: call will be transferred to selected question.
  • TransferToUri: call will be transferred to selected SipUri.
  • TransferToVoiceMailUri: call will be transferred to selected voice mail URI.
  • TransferToPSTN: call will be transferred to selected PSTN (public switched telephone network).
• Prompt <CsRgsPrompt>: The prompt (audio file or Text To Speech) to be played.
• Question <CsRgsQuestion>: The question to transfer the call to.
• QueueID <CsRgsQueue>: Identity of the queue the call should be transferred to.
• Uri <String>: SIP address, voice mail URI or PSTN number the call should be transferred to.

At this point you might have noticed that I introduced a few new Rgs related cmdlets: CsRgsPrompt, CsRgsQuestion and CsRgsQueue. I will not go deep in this post about these objects but let me at least define for you what the goal of this objects is:

-          Prompt: Either an audio file played or a text that is read aloud by the TTS engine in order to supply caller with additional information.

-          Question: Provide the caller with choices (ex: press 1 for English, press 2 for French) and take action based on the callers' answer.

-          Queue: Hold the caller on hold until an agent is eligible to receive the call.

To create a call action you can either use the Lync Server Control Panel or the Lync Server Management Shell. However to add a prompt to a call action you have to use the Lync Server Management Shell.

Figure 1: Configuring a call action via Lync Server Control Panel

Let's create a call action via PowerShell:

1.       Open the Shell or Import the Lync module to your PowerShell console.
           PS C:\> Import-Module Lync

2.       If you want a prompt in you call action, create one
          PS C:\>  $prompt = New-CsRgsPrompt -TextToSpeechPrompt "Please hold the line, you are being transferred to our sales group".

3.       Create your call action object and define an action to your object
           PS C:\>  $ca = New-CsRgsCallAction -Action TransferToUri

4.       Now depending on the action you selected above enter a value in the correct property, not doing so will throw an exception when trying to use this call action with another object.
          PS C:\> $ca.Uri = "Ahmet@vdomain.com"

5.       Attach the prompt to your object
          PS C:\> $ca.Prompt = $prompt

Keep in mind that call actions can have only certain type of action depending on the parent object consuming them, below is a summary of the valid choices:

-          Workflow (NextTarget): TransferToQueue, TransferToQuestion

-          Workflow (BusinessHours, Holiday): Terminate, TransferToUri, TransferToVoiceMailUri

-          Answer: TransferToQueue, TransferToQuestion

-          Queue: Terminate, TransferToQueue, TransferToUri, TransferToVoicemailUri

We now have a call action object in memory ready to be used with either a RgsWorkflow, a RgsAnswer or a RgsQueue.

The object used to hold the collection of agents assigned to a Response Group is called an AgentGroup. Properties from this AgentGroup object are, I believe, straight forward but let's see all of them.

• Name <String>: Unique name assigned to the agent group.
• Parent <RgsIdentity>: The service were the agent group is hosted.
• AgentAlertTime <Int16>: The amount of time (in seconds) a call can remain unanswered before it is automatically routed to the next agent.
• AgentsByUri <SipAddress Collection>: The collection of agents (identified by Sip addresses) of an agent group.
• Description <String>: the description of the agent group, to provide additional information about the agent group. This will not be visible to users (only for admin use).
• DistributionGroupAddress <String>: To add members of a distribution group to an agent group.
• ParticipationPolicy <Informal | Formal>: Indicates whether the agents are required to sign in to the agent group or not.
• RoutingMethod <Longest Idle | Serial | Parallel | RoundRobin | Attendant>: Specifies the method used to route new calls to agents.

There are two ways create new AgentGroup: via the Lync Server Control Panel or via the Lync Server Management Shell (or any PowerShell console).
Let's start with Lync Server Control Panel approach first:

Figure 1: Creating a new group

1. Open the Lync Server Control Panel (https://pool.fqdn.com/CSCP/)
2. Navigate to 'Response Groups' panel
3. Click on the 'Group' tab
4. Click the New button to create a new agent group
5. Select the site that will host the new agent group
6. Enter value to configure your agent group
   • Enter a Name
   • Enter a Description
   • Select the participation policy
   • Select the agent alert time
   • Select the agents that will be part of the agent group (or enter a distribution group address)
7. Commit the changes

Now let's do the same but with the Lync Server Management Shell.

1. Open the Shell or Import the Lync module to your PowerShell console.
   PS C:\> Import-Module Lync
2. Get the service identity that will host your agent group
   PS C:\> $serviceId="service:"+(Get-CSService | ?{$_.Applications -like "*RGS*"}).ServiceId;
3. Create the new agent group (if you don't use the InMemory flag, this agent group will be saved directly in the database).
   PS C:\> $ag = New-CsRgsAgentGroup -Name "My first PS agent group" -Parent $serviceId;
4. Enter a description (optional)
   PS C:\> $ag.Description = "Contain the agents working from 1pm to 6pm";
5. Enter a participation policy
   PS C:\> $ag.ParticipationPolicy = "Formal"
6. Enter the agent alert time
   PS C:\> $ag.AgentAlertTime = "20"
7. Add the agents to the collection
   PS C:\> $ag.AgentsByUri.Add("sip:pool0_agent1@vdomain.com")
   PS C:\> $ag.AgentsByUri.Add("sip:pool0_agent2@vdomain.com")
   PS C:\> $ag.AgentsByUri.Add("sip:pool0_agent3@vdomain.com")
8. Save the changes (if you do it in one line and without the 'InMemory' flag, you don't need to set the agent group a second time).
   PS C:\> Set-CsRgsAgentGroup $ag

You now have your first agent group created and saved in the database! Congrats :-).
Next step will be to create a queue, which is where the callers are placed on hold until an agent from an agent group answer the call.

I am using the Lync Server Management Shell, if I were using another PowerShell I would have to import the Lync Module first:  Import-Module Lync.

• 1. Identify the AD user we want to add:
  $user = Get-CsAdUser |? {$_.FirstName -Like "Ahmet"}
• 2. Enable this AD user to become a Lync Server user.
  $registrar = (Get-CsService |? {$_.Role -like "Registrar"}).PoolFqdn
  Enable-CsUser -Identity $user.Name -RegistrarPool $registrar -SipAddressType SamAccountName -SipDomain "vdomain.com"
• 3. Enable the Lync user to be Enterprise Voice Enabled
  Set-CsUser $user.Id -EnterpriseVoiceEnabled $true

If you forget to enable your agent for enterprise voice you can still add him to an AgentGroup but he will not be eligible to get call from the Response Group (he will not receive any invite). You would see a warning logged in the Event log once Active Directory happen (roughly every 8 hours).

The next step, now that we have valid users, will be to create an AgentGroup.