Wednesday, February 22, 2012

Re-routing Incoming Lync Calls to AutoAttendant Using MSPL Scripting

Many companies assign extensions to their users rather than dedicating a full external phone number.  In companies with thousands of users, this is often the only option, plus it can save significant amounts of money.  If you've followed my Enterprise Voice Best Practices for extensions, then you know that I recommend you assign phone numbers to Lync Enterprise Voice users using the main office number as the base followed by the extension, using the format tel:<OfficeNumberinE164Format>;ext=<Extension>.  For example, if your main office number is 15553334444, and your extension is 222, then your Tel URI would be tel:+15553334444;ext=222.  You then create a normalization rule that takes the main office number and routes it to an Exchange autoattendant at an unused extension, such as tel:+15553334444;ext=999.  When someone calls the main office number, the phone call will be routed to the Exchange autoattendant where they can enter the extension of the user they wish to reach.

This works fine in many deployments, but in situations where the incoming phone number is already formatted in E.164 format (as with many SIP providers), it breaks down.  When Lync sees a number that starts with a +, it assumes the number is normalized properly and does not apply normalization rules, no matter how hard you try.  Users get a busy signal and if you do a log trace, you'll see the error 485 Ambiguous.  Lync sees many users with the same base phone number, and doesn't know where to send the call.

In many of those cases, you can either set your PSTN gateway (if you are using one) to not send the + to Lync, or you can ask your SIP provider to drop the +.  If neither of those options are available, then you can employ MSPL scripting to re-route the incoming call to the appropriate autoattendant.

MSPL scripts are simple text-based programs that can do custom message routing and filtering in Lync.  They can be very powerful, if you know how to create them.  Now, having exactly zero experience with MSPL scripting, I turned to the only way I know how to program:  Google/Bing for examples.  Thanks to some excellent blog posts by Michael Greenlee (which made me hyperventilate because most of it was totally incomprehensible to me) and a terrific example by Lasse Wedø (where he did the bulk of the work for me), I was able to figure out how to make this work in my specific example.

First, copy the contents of the below window into Notepad on a server that is running the Mediation Server role.

Do a search-and-replace for contoso.com and use your public domain name instead.

Then do another search-and-replace for 15552229999 and use your main office number instead.

Finally, do a search-and-replace for Main_AA@contoso.com and replace it with the SIP URI of your Exchange autoattendant or response group.  You can determine the SIP URI by running the OcsUmUtil.exe program (located in C:\Program Files\Common Files\Microsoft Lync Server 2010\Support).  This program is used to create the necessary contact objects to connect Lync to Exchange UM.  Once you click Load Data, make note of the SIP URI for the appropriate AA, and do a search-and-replace for Main_AA@contoso.com in the script using the information you found from OcsUmUtil.

Then save the script on your mediation server/front-end in a folder like C:\MSPLScripts, calling it ReroutePilotNumtoAA.am.  If you have multiple servers in the pool, copy the script to each server.

Now, open Lync Management Shell and type the following (make sure you replace contoso.com with your public domain name):
New-CsServerApplication -Name ReroutePilotNumtoAA -Parent Service:Registrar:
<lyncpoolFQDN> -Uri http://www.contoso.com/ReroutePilotNumtoAA -Enabled $TRUE -Critical $FALSE -ScriptName c:\MSPLScripts\ReroutePilotNumtoAA.am -Priority 2
If all goes well, you should see a few events in the Lync Server Event Viewer like the following:

Log Name:      Lync Server
Source:        LS Script-Only Applications
Event ID:      30803
Description: Loading application - 'c:\MSPLScripts\ReroutePilotNumtoAA.am'

Log Name:      Lync Server
Source:        LS Applications Module
Event ID:      30208
Description: Lync Server application has successfully registered.
Application Uri 'http://www.contoso.com/ReroutePilotNumtoAA'
Open Lync Control Panel and go to Topology - Server Application and you should see the new script between TranslationService and UserServices.

If the script doesn't work you will see the error logged in the Event Viewer.  If so, click Action and Disable Application.  After a few minutes, you should see an event saying the script was disabled.  Make any necessary fixes and re-enable.  It will take a few minutes to restart.  Once you get a clean start, try calling the main office number.  You should be directed to the chosen Exchange autoattendant.

Every time the script runs, it will log a warning event saying that the number was forwarded to the autoattendant.  If you don't want to see this event, comment the line that starts with Log("Event" with a //.

What is happening behind the scenes is that the script is looking for an INVITE for the main office number.  If it sees that, it will respond to the system making the call with a 302 Moved Temporarily.  This tells the system to forward the call to the new destination.

I recommend that you thoroughly document the procedure for future Lync administrators.  If you hand off Lync administration to someone else, it will be very difficult to determine that a script is being used to re-route the office number.  It doesn't make itself known when doing a typical log trace.  If you make a call to the office number, the trace will only show the phone call is going to the AA.  It won't show the script making the forward.

Also, note that this procedure can be used to forward calls to ANY SIP URI, not just an Exchange autoattendant.  It can be an autoattendant, a response group or an individual user.

This is my first foray into MSPL scripting.  If you notice any errors, please let me know.

For more funtastic MSPL examples, check out VOIPNorm's blog.



20 comments:

  1. Thank you for sharing this detailed summary.

    ReplyDelete
  2. Hi Ken
    I am getting invalid Path for script-only application error.. Any suggestions?

    ReplyDelete
  3. Hi Ken,

    I read this and saw it is only for AA , but I work with 5 Response Groups.
    eg one has the number +3237778810 . If there is not user defined with that line URI it works fine, but as soon as I assign tel:+3237778810;ext=15 to a user it stops working.
    Can I use this script also for that problem ?

    ReplyDelete
    Replies
    1. Hi Nick,
      Yes you can use this script to forward calls to any SIP URI. It can be an autoattendant, a response group or even just a individual user.

      In your case, make sure you also assign an extension to your response group, or you will still get the ambiguous issue.

      Ken

      Delete
  4. Hi,

    We're running independent Edge / Mediation server roles. Can you confirm if this needs to be applied on both servers or just the Mediation server?

    Many thanks,

    Mike

    ReplyDelete
    Replies
    1. Hi Mike,
      You only have to apply this script on your mediation servers.

      Ken

      Delete
  5. Hi Ken,

    In my environment we are using one DID for all user's as we don't have extension for all users. So I am using MSPL Scripting to route calls to main number i.e. IVR.
    In my case I want to route calls made to 123456789 (user DID) to 9876543210 (ivr)

    e.g.
    User DID's,
    123456789x1200
    123456789x1201
    Main NUmber ie IVR - 9876543210

    I have followed your guide but no luck. Is inbound normalization rule is required for routing? Please let me know if I am missing anything..

    Thanks in advance.

    ReplyDelete
    Replies
    1. Hey Santosh,
      My script will only allow you to forward to SIP URIs, not actual phone numbers. Your IVR number will have a SIP URI associated with it (assuming its a Lync Response Group). Use that instead of the number, and it should work fine.

      Ken

      Delete
  6. Hey Ken


    I did what you said but no luck,

    My IVR TEL URI is +12345678111;ext=1550
    MY IVR SIP URI is ivr@mytricks.in

    in script I have mentioned my number as +12345678111 without extension number. Please let me know if I am missing anything. Please check below script..

    Thanks in advance..












    ReplyDelete
  7. Hi,

    I had this working lovely on a 2010 but I'm having trouble migrating my mediation services across. When I use it I get this:

    Configured application uri for script-only application did not match application uri in path.

    Path: C:\MSPLScripts\ReroutePilotNumtoAA.am
    Cause: Powershell cmdlets do not parse the contents of the path so they can't detect if the application uri specified in the path matches the application uri specified via the cmdlet.
    Resolution:
    Fix the application uri using Set-CSServerApplication cmdlet to match the application uri in the path.

    Identity : Service:Registrar:pool2013.x.com/RerourePilotNumbertoAA
    Priority : 2
    Uri : http://pool2013.x.com/ReroutePilotNumbertoAA
    Name : RerourePilotNumbertoAA
    Enabled : True
    Critical : False
    ScriptName : C:\MSPLScripts\ReroutePilotNumtoAA.am
    Script :

    ReplyDelete
    Replies
    1. In the URI, try using http://www.x.com/ReRoutePilotNumbertoAA instead.

      Ken

      Delete
    2. Thanks, yeah realised that as I wrote it :)

      Should it be placed as priority 2 in a 2013 environment?

      Thanks again

      Delete
    3. I don't see any reason to change the priority. Glad it works in 2013.

      Ken

      Delete
  8. Hi Ken,
    Thank you for sharing this cool script.
    I tried it and I can see it works as expected.
    I need to route an incoming call to another attendant server (not a Lync response group or an individual Lync user) on the same network of my Lync server.

    The following should be the scenario:

    PSTN_GW (+584365540) -> MS Lync -> PSTN_GW (sip:6440@sas.imagicle.com)

    Is it possible to do this with your script?

    I can call the attendant server (a normal Lync gateway) from a Lync user by calling 6440, so I customized your script in according:
    --------------------------------------------------------------------------------------------------------------------
    if (ContainsString(toUserAtHost, "+584365540@imagicle.com", true))
    {
    Log("Event", 0, "ReroutePilotNumtoAA: Autoattendant match. Re-routing +584365540 to Autoattendant", toUserAtHost);
    Respond("302","Moved Temporarily","Contact=");
    --------------------------------------------------------------------------------------------------------------------

    However when external incoming call come to my Lync server, I get "404 Not Found" message:

    --------------------------------------------------------------------------------------------------------------------
    TL_INFO(TF_PROTOCOL) [1]0914.0F00::02/08/2014-21:25:35.425.0028adae (SIPStack,SIPAdminLog::TraceProtocolRecord:SIPAdminLog.cpp(125))$$begin_record
    Trace-Correlation-Id: 2813426983
    Instance-Id: 000A378A
    Direction: outgoing;source="local"
    Peer: lync2010.imagicle.com:59482
    Message-Type: response
    Start-Line: SIP/2.0 404 Not Found
    From: "Johnny G.";epid=89DB34F77D;tag=565389f8e0
    To: ;tag=2A311F279EC1E2914A023015157E5839
    CSeq: 111070 INVITE
    Call-ID: f264168a-b6bf-44c3-be67-2b16f63f4f71
    ms-application-via: monitorlync.imagicle.com_;ms-server=LYNC2010.imagicle.com;ms-pool=lync2010.imagicle.com;ms-application=51FB453D-5B9F-45df-83B4-ADD1F7E604A8
    Via: SIP/2.0/TLS 192.168.4.40:59482;branch=z9hG4bKb59f069;ms-received-port=59482;ms-received-cid=2687100
    ms-diagnostics: 1003;reason="User does not exist";TargetUri="6440@sas.imagicle.com";source="LYNC2010.imagicle.com"
    Server: RTC/4.0
    Content-Length: 0
    Message-Body: –
    $$end_record
    --------------------------------------------------------------------------------------------------------------------

    Can you help me to fix this issue?

    Thanks in advance

    ReplyDelete
    Replies
    1. Hi Ken,
      I managed to fix the issue by adding a static route in lync that routes the URI provided by your script to the correct IP address of my attendant server.

      However now I have another issue :)

      The SIP INVITE that come from Lync / application script, doesn't include SDP.
      Or better, Lync uses multipart SDP .
      Unfortunately, non-Lync endpoints generally don’t support the multipart/alternative content type for the SDP, and so to them it appears that the message is malformed or missing the SDP.

      So, my new question for you is:
      Are you able to modify your script in order to add a valid (standard) SDP message into the SIP INVITE?

      Please let me know
      Thank you for your time

      Delete
    2. Unfortunately, I'm not much of an expert in MSPL scripting. Another Lync MVP, Michael Greenlee (who I link to in the above post), can likely answer your question much better than me.

      Ken

      Delete
  9. Hey Ken,

    Thanks for the info, I got the sample script to work without an issue for one auto-attendant. Couple of questions here though:
    1) How do we add another auto-attendant in the same script? I've tried adding another 'if' clause by basically copying the sample if clause that works and changing its properties to match the second auto attendant. In this case however I get an ugly Error: System.Data.SqlClient.SqlException (0x80131904): The conversion of the varchar value '4294967295' overflowed an int column. I tried 'else' and 'else if' as well but get the same error. Would I need to add a file for each auto-attendant?

    2)What are your thoughts on running this in a two or more central site scenarios (for example Europe and North America)? Do you see the need to run two or more instances of the custom app pointing to the script(one on each FE)? I'm guessing this would be required if users from another site call the main number that is supposed to be redirected to the AA via internal routing?

    Cheers,
    Max

    ReplyDelete
    Replies
    1. I don't see any reason why adding a second IF statement shouldn't work. Check your syntax. Here's the relevent part. Just change the phone number and SIP domain:

      if (ContainsString(toUserAtHost, "+15552229999@contoso.com", true))
      {
      Log("Event", 0, "ReroutePilotNumtoAA: Autoattendant match. Re-routing +15552229999 to Autoattendant", toUserAtHost);

      Respond("302","Moved Temporarily","Contact=");

      // Return initiative to Lync.
      return;
      }

      As for #2, you certainly can run variants of this in two or more central sites. The script processing is local to the server, so there shouldn't be any issue with running a different variant on another server. In your situation, you will definitely want to do this, because calls coming into the second site will stay local to that site, so you will need this script running on the local servers to capture it.

      Ken

      Delete
    2. Hey Ken,

      Thanks for the quick reply and the insight! For question 2 - as soon as I get the 'if' statement issue fixed I'll probably create a global list which I'll apply to the sites.

      As for the script, here's what I have. If I comment out the second If statement it works fine. Adding the second statement blows the whole thing up. Does the 'return' within the if statement cause an issue maybe?

      //
      // Look for SITE1 AUTO ATTENDANT +15552229999@domain.com in the sipRequest object
      // This is the Attendant no.
      //
      if (ContainsString(toUserAtHost, "+15552229999@domain.com", true))
      {
      Log("Event", 0, "ReroutePilotNumtoAA: Autoattendant match. Re-routing +15552229999 to Site1 Auto Attendant", toUserAtHost);

      Respond("302","Moved Temporarily","Contact=");

      // Return initiative to Lync.
      return;
      }
      //
      // Look for SITE2 AUTO ATTENDANT +445552229999@domain.com in the sipRequest object
      // This is the Attendant No.
      //
      if (ContainsString(toUserAtHost, "+445552229999@domain.com", true))
      {
      Log("Event", 0, "ReroutePilotNumtoAA: Autoattendant match. Re-routing SITE2 DID hook +445552229999 to SITE2 Auto Attendant", toUserAtHost);

      Respond("302","Moved Temporarily","Contact=");

      // Return initiative to Lync.
      return;
      }

      // Return initiative to Lync/Default Routing.
      return;

      Delete
    3. The 'return' shouldn't make a difference since its part of the 'if' statement. I would make sure you have the proper quotes around things. I would try copying and pasting the section that works, and just modifying the number slightly. Maybe you're overflowing a variable with the log statement being too long? Weird though, because the error seems to indicate a problem with an integer variable, while we're using strings everywhere. Send me the entire script in email and I'll have a peek.

      Ken

      Delete