As a Lync Server administrator, you may be asked to configure Lync Server 2010 to perform custom filtering and routing tasks, such as blocking calls from specific numbers, performing a specific action when a specific number is called, performing a routing action based on presence of users, filtering content of instant messages, and appending warning messages to IMs based on the to or from uri. Microsoft SIP Processing Language (MSPL) applications are a great way to perform these common tasks. This article discusses the creation and troubleshooting of MSPL script applications. It does not address SIP managed-code applications. For more information on the differences between MSPL script applications and SIP managed-code applications, see the Resources section of this article.
Author : Santosh More
Publication date : March 14, 2012
Product : Lync Server 2010
Introduction
Using MSPL to design a filter application for Lync Server 2010 is a two-step process. The first step is the creation of the application manifest file that applies the schema to the application along with a script used to filter incoming script requests to the Lync Sever 2010 server component. The second step is to register the application manifest file as an MSPL filter application with the Lync Server 2010 pool.
A Microsoft SIP Processing Language (MSPL) application for Lync Server 2010 is a SIP filtering application that is centric to the type of Lync Server 2010 pool that it is designed for. Typically, a MSPL application is designed for use with a Lync Server 2010 Front End Server, proxy server, or Edge Server pool. The application filters incoming SIP requests using the scripted logic that resides in its application manifest file. To add the application manifest file to the Lync Server 2010 pool as a MSPL application, use the Lync Server Management Shell to issue a specific Windows PowerShell command designed for this task. A MSPL application runs silently in the background on the Lync server where it is installed. The application responds to incoming SIP requests by adding warnings or error events to the Application Event Log. The Microsoft Lync Server 2010 SDK provides standalone executable tools that can compile (compileSPL.exe) and debug (apiLogger.exe) an MSPL script application. Creating, applying, and troubleshooting a MSPL application requires limited programming experience.
Application Manifest File
The MSPL application manifest file typically consists of the following structure: the XML schema definition, the element attributes that define its purpose, the MSPL script that defines the application’s logic, and the log functionality that provides debug logging.
The application manifest file is an XML file (see Figure 1) that can be created and edited with a text editing tool and saved to a local folder on a Lync Server with an .am file extension. It requires the use of a specific XML schema for use with Microsoft Lync Server 2010.
See Creating an Application Manifest for more information.
Figure 1. The application manifest file’s XML template
|
<?xml version="1.0" ?> <lc:applicationManifest lc:appUri="http://www.contoso.com/AudioCallMonitoring" xmlns:lc=http://schemas.microsoft.com/lcs/2006/05> insert_element_attributes_here <lc:splScript> <![CDATA[ insert_message_filter_script_here ]]> </lc:splScript> </lc:applicationManifest> |
The application element attributes define the overall purpose of the application manifest file. They are added to the application manifest file as shown in Figure 2.
Figure 2. Application manifest file with additional element attribute
|
<?xml version="1.0" ?> <lc:applicationManifest lc:appUri="http://www.contoso.com/AudioCallMonitoring" xmlns:lc=http://schemas.microsoft.com/lcs/2006/05> <lc:requestFilter methodNames="INVITE," strictRoute="false" /> <lc:responseFilter reasonCodes="ALL" /> <lc:proxyByDefault action="true" /> <lc:scriptOnly / <lc:splScript> <![CDATA[ insert_message_filter_script_here ]]> </lc:splScript> </lc:applicationManifest> |
See applicationManifest Element for more information.
The MSPL script section of the application manifest file contains the logic of the script that processes the SIP messages of interest. Figure 3 illustrates script logic that extracts the pool FQDN from the SIP URI of a SIP request. If the SIP request contains a pool name, it then determines whether audio/video media is requested.
Figure 3. Add the MPLS script to the application manifest file
|
<?xml version="1.0" ?> <lc:applicationManifest lc:appUri="http://www.contoso.com/appLocation" xmlns:lc=http://schemas.microsoft.com/lcs/2006/05> <lc:requestFilter methodNames="INVITE," strictRoute="false" /> <lc:responseFilter reasonCodes="ALL" /> <lc:proxyByDefault action="true" /> <lc:scriptOnly /> <lc:splScript> <![CDATA[ Log("Event", false, "Entering AudioCallMonitoring.am"); To = GetUri(sipRequest.To); poolServer = QueryHomeServer( To ); if (poolServer == null) { Log("Event", false, "Pool or Home Server is not available", "False" ); return; } messageAudio = false; if (IndexOfString(sipRequest.Content, "m=audio") >= 0){ messageAudio = true; Log("Event", false, "m=audio ", "True");} if (IndexOfString(sipRequest.Content, "m=video") >= 0){ messageAudio = true; Log("Event", false, "m=video ", "True");} return;]]> </lc:splScript> </lc:applicationManifest> |
In Figure 3, the MSPL script illustrates how to design a MSPL application manifest file to audit certain SIP requests. At run time, the contents of this application manifest file are presented to the server agent component of the Lync Server, which uses the application’s extension attributes, along with the conditions defined by its MSPL script, to filter all Incoming SIP INVITE requests that contain audio or video call information, in the SDP section of the SIP packet. For troubleshooting information see the LS Applications Module warning events logged in the Lync Server Event Log see Figure 9 and Figure 10.
For more detailed information on creating application manifest files that contain MSPL scripts, see SIP Application Manifest Reference and MSPL for Message Routing and Filtering .
Deploying MSPL Applications
Deploying a MSPL manifest application to a Lync Server 2010 pool requires the use of the Lync Server Management Shell console to issue the New-CsServerApplication Windows PowerShell cmdlet.
Example:
New-CsServerApplication –Identity “registrar:pool01.contoso.net/AudioCallMonitoring” –Uri http://www.contoso.com/AudioCallMonitoring -ScriptName “c:\msplapps\AudioCallMonitoring.am” –Critical $False –Enabled $True
See New-CsServerApplication for more details.
To update the registered MSPL server application’s extension attributes or to remove the registered MSPL server, use the Set-CsServerApplication or Remove-CsServerApplication PowerShell cmdlets. For detailed information on using these PowerShell cmdlets, see the Resources section of this article. After the MSPL application is registered, its parent service must be restarted to compile and load the application.
Troubleshooting MSPL Applications
Like any script application, there are two types of errors that prevent a MSPL application from performing its task. These errors types are known as compiler errors and runtime errors. Lync Server 2010 provides multiple ways to troubleshoot compilation and registration issues of MSPL application manifest files.
- Lync Server 2010 Event logs.
- Lync Server 2010 SDK CompileSPL and APILogger tools.
- Lync Server 2010 Logging Tool RTCSPL logging.
Lync Server 2010 Event Logs
The Lync Server 2010 Event logs are the most convenient way to troubleshoot a new MSPL application. On startup, the service that the MSPL application (Registrar/EdgeServer/MediationServer) is assigned to logs the MSPL applications compiler and runtime events. After the MSPL application compiles and starts, it logs an informational event in the Lync Server 2010 Event log (see Figure 4).
Figure 4. MSPL application has started without errors
If the MSPL application’s application manifest file does not correctly compile, or has an error that the compiler will not acknowledge, the application will not start and error events are logged to the Lync Server 2010 Event log. Figure 5 and Figure 6 illustrate a scenario where a compiler error stops the MSPL application from starting.
Figure 5. The MSPL manifest application file could not be compiled or contained invalid information
To drill down and locate the cause of the MSPL applications start failure, use the Lync Server 2010 Event log to view the compiler error. This error event points to the location of the error in the MSPLs application’s application manifest file (see Figure 6).
Figure 6. The logged error event notes a compiler error in the application manifest file
After the MSPL application manifest file’s element attribute syntax is corrected, a restart of the services re-compiles the correction and the MPSL application starts. This provides the previously listed informational event in the Lync Server 2010 Event log (see Figure 4).
Compile the MSPL application separately
As mentioned earlier, the compile process requires restarting the Lync Server 2010 service (Registrar/EdgeServer/MediationServer) that the MSPL application is assigned to. This can be a major inconvenience on a Lync Server 2010 network during business hours. To avoid restarting the Lync Server 2010 service to compile your script, the Lync Server 2010 SDK provides a tool, CompileSPL.exe, for this purpose. Run this tool from a command prompt window to compile your MSPL application manifest file (see Figure 7).
Note : The CompileSPL.exe file is located in the following folder, %ProgramFiles%\Microsoft Lync Server 2010\SDK\Bin.
Figure 7. Using the Compile SPL.exe command line tool
Use the APILogger.exe Tool to Debug Applications at Runtime
Like CompileSPL.exe , the APILogger.exe tool is a standalone executable file that ships with the Lync Server 2010 SDK. The APILogger.exe runs from a command prompt on the server hosting the MSPL script application that requires debugging.
The ApiLogger.exe application assists in the debugging MSPL applications. SIP-related errors are registered in the log and can be viewed by running ApiLogger.exe.
To use the APILogger.exe tool, you must restart the Lync Server 2010 service (Registrar/EdgeServer/MediationServer), that the MSPL application is registered with. When started, the MSPL application displays the debug output in the command prompt window. To log debug output, add calls to the Log() function in your MSPL script in the manifest file. For example, the following call:
Log("Debug", false, "Query URI = ", queryUri) ;
displays the following output to the command prompt window in APILogger.exe, when the MSPL script runs:
Query Uri = sip:example@ms.com
This provides a convenient way to test the MSPL script in a lab environment prior to launching it in a production environment.
Note: The APILogger.exe file is located in the folder, %ProgramFiles%\Microsoft Lync Server 2010\SDK\Bin.
Use the Lync Server Logging Tool to Gather RTCSPL Trace Logs
The Lync Server Logging Tool provides RTCSPL trace logging of all MSPL applications start up processes. This provides a quick and easy way to detect issues with a user defined MSPL script application, during the start of that MSPL application’s parent service.
1. Open the Lync Sever Logging Tool.
2. Select the RTCSPL logging feature.
3. Select All and check the All Flags options.
4. Restart the parent service to collect trace logs. The logs identify the issue affecting the MSPL application’s ability to start (see Figure 8).
Figure 8. Lync Server 2010 RTCSPL trace log error
|
Component: RTCSPL Level: TL_ERROR Flag: TF_COMPONENT Function: SPLExecService.ScriptOnlyApplication.Start Source: splexec.cs(484) Local Time: 12/20/2011-06:24:03.425 Sequence# : 00000089 CorrelationId : ThreadId : 0FB4 ProcessId : 1300 CpuId : 1 Original Log Entry : TL_ERROR(TF_COMPONENT) [1]1300.0FB4::12/20/2011-12:24:03.425.00000089 (RTCSPL,SPLExecService.ScriptOnlyApplication.Start:splexec.cs(484))(0000000003AC360B)Compile errors in script path: C:\MSPLApps\MSPLAppManifest.am |
Testing the MSPL application
After the MSPL application is loaded by the assigned Lync Server 2010 service, test the application to see if the expected results occur. The AudioCallMonitoring MSPL application defined in this article is easily tested. To test the application, a Lync 2010 user invites a peer to an IM or A/V call. LS Applications Module Warning events are added to the Lync Server Event Log (see Figure 9 and Figure 10).
Figure 9. The initial Invite request is logged as per the MSPL script
Figure 10. The audio call Invite is logged as per the MSPL script
Summary
When needed, the implementation of MSPL script applications provide an effective way to audit SIP Requests and Responses on any Lync Server 2010 network. MSPL scripts provide administrators with a way to become centric to issues not addressed by standard troubleshooting procedures. A basic understanding of how to create, deploy, and troubleshoot an application manifest file and its MSPL script, is needed to begin this advanced trouble shooting process.
Resources
- MSPL for Message Routing and Filtering
- Microsoft Managed SIP Application API
- SIP Application Manifest Reference
- SIP Application Manifest Example
- Application Server and Services Cmdlets
Lync Server Resources
- Lync Server 2010 Documentation Library
- DrRez blog
- NextHop blog
- Lync Server and Communications Server resources
We Want to Hear from You
