The Problem(s)
Response Groups Service (RGS) is a built-in Lync Server application for automated call flows based on templates or custom designed PowerShell scripts.
Despite it's good integration and decent amount of features, I believe it has a wide margin for improvement. (Take a look at Lync Ideascale and you can see that with 95 votes it's currently the most requested improvement for Lync)
That being said, today I got the following error when adding an existing Agent to an existing Agent group:
After a restart of the RGS Windows Service I also found Event ID 31137 and 31138 from LS Response Group Service stating that it could not find an agent with SIP address XXXX:
The Background
Why does this happen? I knew that the SIP address of the Lync user has been changed after a SIP Domain change .
To explain what is happening here, we have to dig into some RGS internals and explain some basics:
- Lync users handling incoming calls for RGS are called Agents
- Agents are grouped into Groups
- Groups are assigned to Queues
- Incoming calls are directed through a workflow and then forwarded to a specific Queue
A Lync user is considered a RGS Group Agent when he is added to at
least one Agent Group, but he can also be a member of many. An
administrator can assign a user to an Agent Group using PowerShell or Lync Control Panel.
The Deep Dive
Now let's have a look how RGS handles this internally.
The RGS application has two specific databases: rgsconfig and rgsdyn:
The rgsconfig database contains the RGS configuration while rgsdyn contains "dynamic" data like current signed in agents and instances.
Within the rgsconfig database we will find a table called Agents:
The Agents table has the following structure:
In troubleshooting this issue the following 3 fields are important:
- ID: a unique GUID, specific to RGS database
- UserSid: a unique Active Directory user identifier (user SID)
- SipAddress: the Lync User's SIP Address
Internally RGS works with the ID field when mapping Agent Groups to Agents as you can see in the table AgentGroupsToAgentsMap):
When adding a user to an Agent Group, the Response Group service will check if the user already exists. The key for our problem is how RGS performs this lookup: based on what information?
After studying it's behavior we can only conclude it does this based on the user SIP Address:
- After changing the SIP Address of an agent, RGS was unable to map the existing agent record to an AD object (see Event Log).
- When adding the same user (with new SIP Address) to an Agent Group, RGS was not able to find the existing Agent record with the old SIP Address.
- Because it could not find the Agent record, it will try to add a new agent record into the table. This action fails because the AD UserSid must be unique and a record with the old SIP Address and same SID is still present.
We now found the root cause for the error
The Solution(s)
The Supported Way
Before changing the SIP Address of a user, remove the user from all Agent Groups he's currently assigned to (as described in KB2393943).
Then, add the user with his new SIP Address back to the Agent Groups.
Sounds like great fun if you ever need to change SIP domain and have 50 agents, right?
The UNsupported Way
Disclaimer: editing a Lync database table is unsupported. You'll do this at your own risk/responsibility
Use SQL Management studio to update the user SIP Address in the Agents table. To edit a few rows you can use the "Edit Top 200 Rows" menu item on the table property menu:
You can then look for the agent record and then change the SIP Address field to the new SIP Address. I would recommend restarting the RGS Windows Service afterwards.
Feel free to post any feedback, cheers