MSPL Script How-to

Microsoft SIP Processing Language [MSPL], is a scripting language that you can use to customize how Lync Server handles and routes SIP messages. MSPL scripts run in the context of the Lync Server process itself (in the front end), so they can intercept messages between users, filter messages, reroute messages, and so on.

MSPL unlike UCMA applications, they don’t run as a separate process, nor do they create endpoints of their own. they aren’t limited to controlling messages to and from a single endpoint it deals with all endpoints of that Lync Server.

How you can decide to use MSPL or UCMA?

1. MSPL
   • The MSPL code itself is included directly in the application manifest.
   • The MSPL modifies the Front End behavior of the Lync Server. It has control over every message that is proxied through the Front End Server, regardless of where it comes from which endpoint or where it goes.

1. UCMA
   • The UCMA application runs on a separate server from Lync Server, and creates an endpoint which communicates with other Lync endpoints via the Lync Front End Server.
   • The UCMA application can participate in and control a conversation between the remote endpoint and itself but can’t control other conversations between other endpoints that are not in the same conversation.

MSPL Script Structure

The following is the form that your MSPL script must be which is an ordinary XML file. The application Manifest is an XML file can be edited using any XML editor, Text editor or even you can open it using Microsoft Visual Studio, so you will find it started with the xml declaration, The following script to filter the sip requests that used to join conference as follow:

<?xml version="1.0" ?>

<lc:applicationManifest
    lc:appUri="http://www.microsoft.com/LCS/FilterConf"
    xmlns:lc="http://schemas.microsoft.com/lcs/2006/05">

    <!-- Define properties of the application -->
    <lc:requestFilter methodNames="INVITE" 
                      strictRoute="true" 
                      registrarGenerated="true"
                      domainSupported="false"/>
    <lc:responseFilter reasonCodes="NONE" />
    <lc:proxyByDefault action="true" />

    <!-- The message filtering script -->
    <lc:splScript><![CDATA[

if (sipRequest && (sipRequest.Method == StandardMethod.Invite)) 
{
    if (sipRequest)
    {
        Log("Event", false, "Joined the conference");
	DispatchNotification("OnRequest", sipMessage.To);
        ProxyRequest();
    }
}

    ]]></lc:splScript>
</lc:applicationManifest>

MSPL Script Syntax

<lc:applicationManifest
    lc:appUri="http://www.microsoft.com/LCS/FilterConf"
    xmlns:lc="http://schemas.microsoft.com/lcs/2006/05">

the root element of the MSPL script is the <lc:applicationManifest> it contains the appUri attribute, which is basically a unique identifier for your application and you need it when you installing your application to the Lync Server.

<lc:requestFilter methodNames="INVITE" strictRoute="false"/>

Using the <lc:requestFilter> you can control what types of messages this application should handle so it controls the types of requests. it contains the methodNames attribute which can contains a list of SIP method names separated by commas i.e. invite also can monitor ALL method names or NONE of them. the next one is strictRoute attribute, which is false by default, controls whether the application sees requests for which explicit routing details have already been specified. If this is set to true, these messages that have a “strict” route will also go through the application.

<lc:responseFilter reasonCodes="NONE" />

The <lc:responseFilter> also specify what types of messages this application should handle and contain The reasonCodes attribute holds a comma-delimited list of SIP response codes, or ALL, or NONE.

<lc:proxyByDefault action="true" />

The <lc:proxyByDefault> element, which is used to decide how application will handle the sip message by setting the action attribute, If this is set to false, any messages that are not proxied, responded to, or otherwise handled by the application are simply dropped. If it’s true, messages that are not handled are proxied to their destination by Lync Server, just as they would were the application not installed.

<lc:scriptOnly />

If application will consist only of an MSPL script, and will not use any managed code, we can add the <lc:scriptOnly /> element, if not there is no need to add it.

<lc:splScript>
    <![CDATA[ /* Start writing your script here */ ]]>
</lc:splScript>

After that The MSPL script itself is included in the manifest within the <lc:splScript> element.

if (sipRequest) {
    /* do something */
    Log("Event", false, "Log somthing - ", sipMessage.To);
}
if (sipResponse) {
    /* do something else */
}

If you need to access the message. The sipMessage variable provides access to a class that contains the message details. However, in many cases, the application’s behavior will depend on whether it is handling a request or a response; and the data available will depend on which type of message it is. the same as sipResponse if you want to access the response.

Helpful References

• MSPL Scripting Reference
• MSPL Script Sample as Message Filter