Topic Last Modified: 2012-08-11

Modifies an existing Response Group workflow. Workflows determine the actions that are taken when the Response Group application receives a phone call. This cmdlet was introduced in Lync Server 2010.


Set-CsRgsWorkflow -Instance <Workflow> [-Confirm [<SwitchParameter>]] [-Force <SwitchParameter>] [-WhatIf [<SwitchParameter>]]



The commands shown in Example 1 retrieve an existing set of business hours, and then assign those business hours to a workflow named Help Desk. To do this, the first command in the example uses Get-CsRgsHoursOfBusiness to retrieve the business hours collection named U.S. Business Hours from the service These business hours are stored in a variable named $businessHours.

After the business hours have been retrieved the Get-CsRgsWorkflow cmdlet is used to retrieve the Help Desk workflow from This object is stored in a variable named $y.

In the third command in the example, the BusinessHoursId property of the Help Desk workflow is set to the retrieved collection of business hours; that’s done by setting BusinessHoursId to the Identity of the retrieved collection ($businessHours.Identity). In the final command, Set-CsRgsWorkflow is used to write the new business hours to the actual Help Desk workflow on This last step is important because, until this point, all the changes have taken place only in memory. To actually save these changes to the Help Desk workflow, you must call Set-CsRgsWorkflow, passing the cmdlet the object reference ($y) containing the virtual copy of the workflow.

Copy Code
$businessHours = Get-CsRgsHoursOfBusiness -Name "US Business Hours"
$y = Get-CsRgsWorkflow -Name "Help Desk"
$y.BusinessHoursId = $businessHours.Identity
Set-CsRgsWorkflow -Instance $y


Example 2 assigns a new description to the Help Desk workflow found on the service To do this, the first command in the example retrieves the specified workflow (-Name "Help Desk") and stores the retrieved object in a variable named $x. In command 2, a new description ("Workflow for the Redmond Help Desk") is added to the virtual copy of the Help Desk workflow. After the description has been changed, command 3 uses the Set-CsRgsWorkflow to write these changes back to the actual Help Desk workflow located on

Copy Code
$x = Get-CsRgsWorkflow -Name "Help Desk"
$x.Description = "Workflow for the Redmond Help Desk" 
Set-CsRgsWorkflow -Instance $x


The commands shown in Example 3 import a new Response Group audio file, then assign this audio file to an existing workflow. To do this, the first command in the example imports the new audio file. This is done by calling the Get-Content cmdlet in order to read in the audio file (C:\MediaFiles\Hold.wav) byte-by-byte; to ensure that the audio file is read in correctly, you must include the ReadCount parameter (set to 0) and the Encoding parameter (set to Byte). After the audio file has been read in, the data is piped to New-CsRgsAudioFile, which creates a new file on An object reference to this file(which has the name HelpDeskHoldMusic.wav), is stored in a variable named $musicFile.

After the audio file has been created, command 2 retrieves the workflow Help Desk from, storing the returned object in a variable named $y. In command 3, the CustomMusicOnHoldFile property for this workflow is assigned the value $musicFile, which is the variable containing the newly-created audio file.

After $musicFile has been assigned to CustomMusicOnHoldFile, the final command uses the Set-CsRgsWorkflow cmdlet to write these changes back to the Help Desk. workflow

Copy Code
$musicFile = Get-Content -ReadCount 0 -Encoding Byte C:\MediaFiles\Hold.wav | Import-CsRgsAudioFile -Identity -FileName "HelpDeskHoldMusic.wav"
$y = Get-CsRgsWorkflow -Identity -Name "Help Desk"
$y.CustomMusicOnHoldFile = $musicFile
Set-CsRgsWorkflow -Instance $y

Detailed Description

Workflows are perhaps the key element in the Response Group application. Each workflow is uniquely associated with a phone number; when someone calls that number, the workflow determines how the call will be handled. For example, the call might be routed to a series of interactive voice response (IVR) questions that prompt the caller to enter additional information (for example, "Press 1 for hardware support. Press 2 for software support.") Alternatively, the call might be placed in a queue and the caller put on hold until an agent is available to answer the call. The availability of agents to answer calls is also dictated by the workflow: workflows are used to configure both business hours (the days of the week and the times of day when agents are available to answer calls) and holidays (days when no agents are available to answer calls).

The Set-CsRgsWorkflow cmdlet provides a way for you to modify the properties of an existing workflow; for example, you can change the phone number for a workflow, the agents groups associated with a workflow, or the default action to be taken any time the workflow is triggered (that is, any time someone calls the phone number associated with the workflow).

Set-CsRgsWorkflow does not directly modify a workflow itself. Instead, if you need to make changes to a workflow, you must first use Get-CsRgsWorkflow to create an object reference to that workflow; this simply means that you retrieve the workflow of interest and then store the returned object in a variable. After the object reference has been created, you modify the properties of the object in memory, and then use Set-CsRgsWorkflow to write these changes back to actual Response Group application workflow. If you do not call Set-CsRgsWorkflow then your changes will exist only in memory, and will disappear as soon as you close Windows PowerShell or delete the object reference variable.

Who can run this cmdlet: By default, members of the following groups are authorized to run the Set-CsRgsWorkflow cmdlet locally: RTCUniversalServerAdmins. To return a list of all the role-based access control (RBAC) roles this cmdlet has been assigned to (including any custom RBAC roles you have created yourself), run the following command from the Windows PowerShell prompt:

Get-CsAdminRole | Where-Object {$_.Cmdlets –match "Set-CsRgsWorkflow"}


Parameter Required Type Description




Object reference to the Response Group application workflow to be modified. An object reference is typically retrieved by using the Get-CsRgsWorkflow cmdlet and assigning the returned value to a variable; for example, this command returns an object reference to the Help Desk workflow and stores that object reference in a variable named $x:

$x = Get-CsRgsWorkflow -Name "Help Desk"

The Instance parameter is a positional parameter: it can be omitted as long as the object reference to the workflow is the first parameter value used in your command. That means that the following two commands are functionally identical:

Set-CsRgsWorkflow –Instance $x

Set-CsRgsWorkflow $x




Prompts you for confirmation before executing the command.




Suppresses the display of any non-fatal error message that might occur when running the command.




Describes what would happen if you executed the command without actually executing the command.

Input Types

Microsoft.Rtc.Rgs.Management.WritableSettings.Workflow object. Set-CsRgsWorkflow accepts pipelined instances of the Response Group workflow object.

Return Types

Set-CsRgsWorkflow does not return any objects or values. Instead, the cmdlet modifies existing instances of the Microsoft.Rtc.Rgs.Management.WritableSettings.Workflow object.

See Also