Installing and troubleshooting MSPL scripts

In my last post, I described some of the basics of Microsoft SIP Processing Language, or MSPL, using a simple script as an example. That last post ended with a cliffhanger: how does the MSPL script get installed on the Lync Front End Server?

Today, I’m going to answer that question.

Picking up where we left off, we have an application manifest file called Simple.am. I’ve taken the liberty of saving it to my Front End Server at C:\Simple.am. Normally, you’d probably want to put it somewhere else, but I’ll leave it there for simplicity.

The next step is to open up Lync Server Management Shell, which you can find at Start -> Microsoft Lync Server 2010 -> Lync Server Management Shell. It’s very likely you’ve used it before, if you’ve done any Lync configuration or created trusted application objects for your UCMA applications. If not, there are some excellent resources at http://blogs.technet.com/b/csps/.

To start, you can see all the existing server applications by running the Get-CsServerApplication command. Most will have an identity that starts with Service:Registrar, indicating that they are running on the Front End Server. (It’s perfectly possible to have an application running on another server, though, such as the Edge Server.) The priority value indicates the order in which the applications are started and the order in which they get to process requests. Lower values indicate higher priority. So the application with priority 0 will be started first and will handle requests before all of the others get to handle them.

To install our Simple.am script, we need to use the New-CsServerApplication command. Here’s what we’ll need to enter into PowerShell:

New-CsServerApplication -Identity "Service:Registrar:server.domain/Simple"
   -Uri "http://mspl.greenl.ee/simple" -ScriptName "C:\Simple.am"
   -Enabled $true -Critical $true

Let’s go through the parameters one by one. The Identity parameter starts with Service:Registrar: to indicate that this script applies to the registrar, a.k.a. Front End Server, followed by the FQDN of the server itself. After this is a slash, followed by the name of the application, which can be whatever you want.

You may remember that in the script, we set a URI for the script in the root element, using the appUri attribute:

<lc:applicationManifest appUri="http://mspl.greenl.ee/simple" xmlns:lc="http://schemas.microsoft.com/lcs/2006/05">

This is the URI you pass in as the Uri parameter. This identifies the application, and if it doesn’t match what you entered in the application manifest, the application will not load.

The ScriptName parameter, which is named a bit confusingly, should contain the path to the .am file.

The Enabled parameter is self-explanatory: if you want your application to run, it should be set to true; otherwise it should be false.

The Critical parameter determines whether Lync Server can start if your application does not start for some reason. Here, it’s set to true, but if your script is not absolutely required, you can set it to false to avoid bringing down the server if your script doesn’t work. You might want to leave it set to true if you’re using your script for something like legal compliance, and it shouldn’t be possible to bypass it even if it’s not functioning.

Once you run this command, the script will be installed. You can rerun Get-CsServerApplication to verify that it is now listed. If you need to change any of the settings, use the Set-CsServerApplication command.

Next, in order for the script to be loaded, we need to restart the Lync services. You can do this through PowerShell using the Stop-CsWindowsService and Start-CsWindowsService commands, or through the Lync Server Control Panel.

Now, because Visual Studio doesn’t check the syntax of the MSPL scripts, it’s not uncommon to have an error in the application manifest file. If this is the case, the application won’t start properly. To check that the application has started, you can take a look at the Lync Server log in the Event Viewer.

If something went wrong, you’ll likely see a message like this:

Generally, you’ll see one or more other error messages in the vicinity that will tell you a bit more about the problem:

By looking at these messages, you can generally figure out what the problem is, and go back to your .am file to correct it, after which you’ll need to restart the Lync services to try again.

When the application loads successfully, instead of error messages you’ll see a message like this:

At this point, you can try out the application by sending some messages.

I’ve still only scratched the surface of what you can do with MSPL. In future posts, I’ll explain how you can reroute requests to a UCMA application, perform filtering of different kinds, and insert SIP headers or message content.