Appendix F - Using multiple disclaimers

  • Article

 

Applies to: Microsoft Antigen

Antigen supports multiple SMTP disclaimers for outgoing e-mail messages. With multiple disclaimers, administrators can create custom disclaimers that can be appended to mail that is destined for certain domains or recipients, or for mail that is from certain senders or domains. They can also customize disclaimers based on the encoding type that is used in the message.

Antigen uses an XML document to review the sender and recipient address information of an outgoing message to determine which disclaimer should be used. An XML formatted string is entered into the Disclaimer Text dialog box in the Antigen user interface (UI), and the client validates that it is well-formed XML. If there is a syntax problem, an error message appears when you click the OK button. When a disclaimer is added to an outgoing message, the sender and recipient information is gathered and processed to select the correct disclaimer text from the XML formatted string.

The following code provides an example of well-formed XML text that can be used as a template. This example can be modified to suit the administrator’s needs, and then copied and pasted into the client Disclaimer Text dialog box.

XML Disclaimer Text

<?xml version='1.0'?>

<xsl:stylesheet xmlns:xsl="https://www.w3.org/1999/XSL/Transform" version="1.0">

<xsl:template match="/">

<result>

<xsl:apply-templates/>

</result>

</xsl:template>

<xsl:template match="//sender">

<xsl:choose>

<xsl:when test="@name='Administrator'">

<use group-number="4"/>

</xsl:when>

<xsl:when test="@address='helen@yahoo.com'">

<use group-number="3"/>

</xsl:when>

<xsl:when test="@domain='hotmail.com'">

<use group-number="2"/>

</xsl:when>

</xsl:choose>

</xsl:template>

<xsl:template match="//recipient">

<xsl:choose>

<xsl:when test="contains(@name,'mary')">

<use group-number="5"/>

</xsl:when>

<xsl:when test="contains(@address,'jane@gadget.com')">

<use group-number="6"/>

</xsl:when>

<xsl:when test="contains(@domain,'acme.com')">

<use group-number="7"/>

</xsl:when>

</xsl:choose>

</xsl:template>

<xsl:template match="//groups">

<groups>

<group number="1">

<disclaimers encoding="iso-8859-1">

<disclaimer type="html"><br/><a href="https://www.microsoft.com">Click here!</a><br/>Group 1: default disclaimer, iso-8859-1, html...</disclaimer>

<disclaimer type="plaintext">Group 1: default disclaimer, iso-8859-1, plaintext...</disclaimer>

</disclaimers>

<disclaimers encoding="utf-7">

<disclaimer type="html"><br/><a href="https://www.microsoft.com">Click here!</a><br/>Group 1: default disclaimer, utf-7, html...</disclaimer>

<disclaimer type="plaintext">Group 1: default disclaimer, utf-7, plaintext...</disclaimer>

</disclaimers>

</group>

<group number="2">

<disclaimers encoding="iso-8859-1">

<disclaimer type="html"><br/>Group 2: sender domain disclaimer, iso-8859-1, html...</disclaimer>

<disclaimer type="plaintext">Group 2: sender domain disclaimer, iso-8859-1, plaintext...</disclaimer>

</disclaimers>

<disclaimers encoding="utf-7">

<disclaimer type="html"><br/>Group 2: sender domain disclaimer, utf-7, html...</disclaimer>

<disclaimer type="plaintext">Group 2: sender domain disclaimer, utf-7, plaintext...</disclaimer>

</disclaimers>

</group>

<group number="3">

<disclaimers encoding="iso-8859-1">

<disclaimer type="html"><br/>Group 3: sender address disclaimer, iso-8859-1, html...</disclaimer>

<disclaimer type="plaintext">Group 3: sender address disclaimer, iso-8859-1, plaintext...</disclaimer>

</disclaimers>

<disclaimers encoding="iso-2022-jp">

<disclaimer type="html"><br/>Group 3: sender address disclaimer, 日本語のテキスト iso-2022-jp, html...</disclaimer>

<disclaimer type="plaintext">Group 3: sender address disclaimer, 日本語のテキスト iso-2022-jp, plaintext...</disclaimer>

</disclaimers>

<disclaimers encoding="Big5">

<disclaimer type="html"><br/>Group 3: sender address disclaimer, 中國語言聲明 Big5, html...</disclaimer>

<disclaimer type="plaintext">Group 3: sender address disclaimer, 中國語言聲明 Big5, plaintext...</disclaimer>

</disclaimers>

</group>

<group number="4">

<disclaimers encoding="iso-8859-1">

<disclaimer type="html"><br/>Group 4: sender display name disclaimer, iso-8859-1, html...</disclaimer>

<disclaimer type="plaintext">Group 4: sender display name disclaimer, iso-8859-1, plaintext...</disclaimer>

</disclaimers>

<disclaimers encoding="utf-8">

<disclaimer type="html"><br/><a href="https://www.microsoft.com" >Click here.</a>Group 4: sender display name disclaimer, utf-8, html...</disclaimer>

<disclaimer type="plaintext">Group 4: sender display name disclaimer, utf-8, plaintext...</disclaimer>

</disclaimers>

</group>

<group number="5">

<disclaimers encoding="iso-8859-1">

<disclaimer type="html"><br/>Group 5: recipient display name disclaimer, iso-8859-1, html...</disclaimer>

<disclaimer type="plaintext">Group 5: recipient display name disclaimer, iso-8859-1, plaintext...</disclaimer>

</disclaimers>

<disclaimers encoding="utf-7">

<disclaimer type="html"><br/>Group 5: recipient display name disclaimer, utf-7, html...</disclaimer>

<disclaimer type="plaintext">Group 5: recipient display name disclaimer, utf-7, plaintext...</disclaimer>

</disclaimers>

</group>

<group number="6">

<disclaimers encoding="iso-8859-1">

<disclaimer type="html"><br/>Group 6: recipient address disclaimer, iso-8859-1, html...</disclaimer>

<disclaimer type="plaintext">Group 6: recipient address disclaimer, iso-8859-1, plaintext...</disclaimer>

</disclaimers>

<disclaimers encoding="utf-7">

<disclaimer type="html"><br/>Group 6: recipient address disclaimer, utf-7, html...</disclaimer>

<disclaimer type="plaintext">Group 6: recipient address disclaimer, utf-7, plaintext...</disclaimer>

</disclaimers>

</group>

<group number="7">

<disclaimers encoding="iso-8859-1">

<disclaimer type="html"><br/>Group 7: recipient domain disclaimer, iso-8859-1, html...</disclaimer>

<disclaimer type="plaintext">Group 7: recipient domain disclaimer, iso-8859-1, plaintext...</disclaimer>

</disclaimers>

<disclaimers encoding="utf-7">

<disclaimer type="html"><br/>Group 7: recipient domain disclaimer, utf-7, html...</disclaimer>

<disclaimer type="plaintext">Group 7: recipient domain disclaimer, utf-7, plaintext...</disclaimer>

</disclaimers>

</group>

</groups>

</xsl:template>

</xsl:stylesheet>

------------------------------------------

XML Sample Review

  1. The first section of the preceding XML document will try to match the sender information:
    <xsl:template match="//sender">
    <xsl:choose>
    <xsl:when test="@name='Administrator'">
    <use group-number="4"/>
    </xsl:when>
    <xsl:when test="@address='helen@yahoo.com'">
    <use group-number="3"/>
    </xsl:when>
    <xsl:when test="@domain='hotmail.com'">
    <use group-number="2"/>
    </xsl:when>
    </xsl:choose>
    </xsl:template>
    If the sender name is Administrator, the group-number 4 disclaimer is used. If the sender address is helen@yahoo.com, the group-number 3 disclaimer is used. If the sender address has the domain hotmail.com, the group-number 2 disclaimer text is used.

  2. The second section of the document will try to match the recipient information:
    <xsl:template match="//recipient">
    <xsl:choose>
    <xsl:when test="contains(@name,'mary')">
    <use group-number="5"/>
    </xsl:when>
    <xsl:when test="contains(@address,'jane@gadget.com')">
    <use group-number="6"/>
    </xsl:when>
    <xsl:when test="contains(@domain,'acme.com')">
    <use group-number="7"/>
    </xsl:when>
    </xsl:choose>
    </xsl:template>
    If the recipient name contains “mary,” the group-number 5 disclaimer is used. If the recipient address contains “jane@gadget.com,” the group number 6 disclaimer is used. If the recipient address domain contains “acme.com,” the group-number 7 disclaimer text is used.

  3. The last section of the XML document performs group matching.

    Note

    There can be different disclaimers based on the encoding used in the message, as well as on the content type of the message.

    <xsl:template match="//groups">
    <groups>
    <group number="1">
    <disclaimers encoding="iso-8859-1">
    <disclaimer type="html"><br/><a href="https://www.microsoft.com">Click here!</a><br/>Group 1: default disclaimer, iso-8859-1, html...</disclaimer>
    <disclaimer type="plaintext">Group 1: default disclaimer, iso-8859-1, plaintext...</disclaimer>
    </disclaimers>
    <disclaimers encoding="utf-7">
    <disclaimer type="html"><br/><a href="https://www.microsoft.com">Click here!</a><br/>Group 1: default disclaimer, utf-7, html...</disclaimer>
    <disclaimer type="plaintext">Group 1: default disclaimer, utf-7, plaintext...</disclaimer>
    </disclaimers>
    </group>
    <group number="2">
    <disclaimers encoding="iso-8859-1">
    <disclaimer type="html"><br/>Group 2: sender domain disclaimer, iso-8859-1, html...</disclaimer>
    <disclaimer type="plaintext">Group 2: sender domain disclaimer, iso-8859-1, plaintext...</disclaimer>
    </disclaimers>
    <disclaimers encoding="utf-7">
    <disclaimer type="html"><br/>Group 2: sender domain disclaimer, utf-7, html...</disclaimer>
    <disclaimer type="plaintext">Group 2: sender domain disclaimer, utf-7, plaintext...</disclaimer>
    </disclaimers>
    </group>
    <group number="3">
    <disclaimers encoding="iso-8859-1">
    <disclaimer type="html"><br/>Group 3: sender address disclaimer, iso-8859-1, html...</disclaimer>
    <disclaimer type="plaintext">Group 3: sender address disclaimer, iso-8859-1, plaintext...</disclaimer>
    </disclaimers>
    <disclaimers encoding="iso-2022-jp">
    <disclaimer type="html"><br/>Group 3: sender address disclaimer, 日本語のテキスト iso-2022-jp, html...</disclaimer>
    <disclaimer type="plaintext">Group 3: sender address disclaimer, 日本語のテキスト iso-2022-jp, plaintext...</disclaimer>
    </disclaimers>
    <disclaimers encoding="Big5">
    <disclaimer type="html"><br/>Group 3: sender address disclaimer, 中國語言聲明 Big5, html...</disclaimer>
    <disclaimer type="plaintext">Group 3: sender address disclaimer, 中國語言聲明 Big5, plaintext...</disclaimer>
    </disclaimers>
    </group>
    <group number="4">
    <disclaimers encoding="iso-8859-1">
    <disclaimer type="html"><br/>Group 4: sender display name disclaimer, iso-8859-1, html...</disclaimer>
    <disclaimer type="plaintext">Group 4: sender display name disclaimer, iso-8859-1, plaintext...</disclaimer>
    </disclaimers>
    <disclaimers encoding="utf-8">
    <disclaimer type="html"><br/><a href="https://www.microsoft.com" >Click here.</a>Group 4: sender display name disclaimer, utf-8, html...</disclaimer>
    <disclaimer type="plaintext">Group 4: sender display name disclaimer, utf-8, plaintext...</disclaimer>
    </disclaimers>
    </group>
    <group number="5">
    <disclaimers encoding="iso-8859-1">
    <disclaimer type="html"><br/>Group 5: recipient display name disclaimer, iso-8859-1, html...</disclaimer>
    <disclaimer type="plaintext">Group 5: recipient display name disclaimer, iso-8859-1, plaintext...</disclaimer>
    </disclaimers>
    <disclaimers encoding="utf-7">
    <disclaimer type="html"><br/>Group 5: recipient display name disclaimer, utf-7, html...</disclaimer>
    <disclaimer type="plaintext">Group 5: recipient display name disclaimer, utf-7, plaintext...</disclaimer>
    </disclaimers>
    </group>
    <group number="6">
    <disclaimers encoding="iso-8859-1">
    <disclaimer type="html"><br/>Group 6: recipient address disclaimer, iso-8859-1, html...</disclaimer>
    <disclaimer type="plaintext">Group 6: recipient address disclaimer, iso-8859-1, plaintext...</disclaimer>
    </disclaimers>
    <disclaimers encoding="utf-7">
    <disclaimer type="html"><br/>Group 6: recipient address disclaimer, utf-7, html...</disclaimer>
    <disclaimer type="plaintext">Group 6: recipient address disclaimer, utf-7, plaintext...</disclaimer>
    </disclaimers>
    </group>
    <group number="7">
    <disclaimers encoding="iso-8859-1">
    <disclaimer type="html"><br/>Group 7: recipient domain disclaimer, iso-8859-1, html...</disclaimer>
    <disclaimer type="plaintext">Group 7: recipient domain disclaimer, iso-8859-1, plaintext...</disclaimer>
    </disclaimers>
    <disclaimers encoding="utf-7">
    <disclaimer type="html"><br/>Group 7: recipient domain disclaimer, utf-7, html...</disclaimer>
    <disclaimer type="plaintext">Group 7: recipient domain disclaimer, utf-7, plaintext...</disclaimer>
    </disclaimers>
    </group>
    </groups>
    Group number 1 is the default disclaimer. If there are no matches to the other disclaimer groups, the default disclaimer is used.
    Group number 1 also has two disclaimer options. If the message body is encoded in iso-8859-1, there are two possible disclaimer choices. If the content type of the message body is html, the disclaimer text is "<br/><a href="www.microsoft.com">Click here!</a><br/>Group 1: default disclaimer, iso-8859-1, html...,"
    If the content type of the message body is plain text, the disclaimer text is "Group 1: default disclaimer, iso-8859-1, plaintext...." The disclaimer text is what appears between the <xxx> and </disclaimer>.
    The second section in group 1 is for utf-7 encoding. If the content type is html, the disclaimer is "<br/><a href="www.microsoft.com">Click here!</a><br/>Group 1: default disclaimer, utf-7, html...".
    If the content type is plain text, the disclaimer is "Group 1: default disclaimer, utf-7, plaintext...."

Note

The comparisons are case-insensitive, so "Administrator" and "administrator" are treated identically. The groups can contain as many encoding types or content types as necessary.

Each encoding must have one HTML disclaimer text and one plain-text disclaimer text. The two disclaimer texts can be the same for each content type, but there must be one of each. If more than one match is possible, only the disclaimer corresponding to the first match is used. To ensure backward compatibility, if the disclaimer text is not an XML document, then the entire text is used as the disclaimer.

If the encoding type for a specific disclaimer group cannot be matched, the ISO-8859 disclaimer for that group is appended to the message.

If you are using NT4, for some encoding types no disclaimer can be appended to the e-mail message for the recipient. This is true with the iso-2022-jp encoding. This is caused by a problem in a Microsoft® function that encodes the Japanese characters. The function thinks the characters are invalid. Consequently, the disclaimer text is not encoded and a string of length zero is appended. Microsoft has corrected the problem in Windows® 2000 and later.

When editing the XML document for RECIPIENT DISPLAY NAME in Windows NT4, you must append "(E-mail)" to the Display Name. For example, a display name of JSmith must be entered in the XML document as JSmith (E-mail).

Disclaimer hierarchy

If both sender and recipient information is included in the multiple disclaimers, the sender match will take precedence over recipient. This is true even if the administrator places the recipient matching section to precede the sender matching section. Therefore, if a match is found in both the sender and recipient section, the disclaimer group that is associated with the matching sender is used.

Similarly, if multiple matches are found in either the sender section or the recipient section, the disclaimer group that is associated with the first match is used. For example, if two recipient domain matches are listed in the XML document and the first one matches the domain of one of the recipients of the e-mail message, and the second one matches the domain of another recipient of the e-mail message, then the disclaimer group that is associated with the first recipient domain is used.

Additional sample disclaimer text

Additional sample disclaimer files are included in the Antigen installation folder. The three sample files include:

  • **Full Functionality Multiple Disclaimer.xsl—**For organizations that require full functionality of multiple disclaimers, this file contains the sample used earlier and would be the appropriate starting point for creating a full-functionality multiple disclaimer.
  • **OneDisclaimer NoSenderRecipient FixedEncoding.xsl—**For organizations that do not require different disclaimers for different senders/recipients and do not need to worry about encoding, but want to have a different disclaimer for plain text and HTML message bodies, this file is the appropriate template for creating a custom disclaimer.
  • **OneGroup NoSenderRecipient MultipleDisclaimers.xsl—**For organizations that do not require different disclaimers for different senders or recipients but want to have different disclaimers for different encoding types, this file is the appropriate template for creating a custom disclaimer.

Each file must be modified to suit the specific needs of your environment and for the actual disclaimer text you would like to use. When the disclaimer has been modified, you must copy and paste the code into the disclaimer edit box.

Important

When Antigen appends a disclaimer to an e-mail message that has a different encoding, such as iso-2022-jp, it uses the MS API WideCharToMultiByte to convert the Unicode disclaimer text to the format needed before appending it to the message. If support for the particular encoding has not been installed on the server (in Control Panel, double-click Regional and Language Options, and then click the Languages tab), Antigen will not be able to create a disclaimer in the appropriate encoding. If this occurs, a blank disclaimer is added to the message, and the following error is logged to the ProgramLog: "WideCharToMultiByte returns an empty string for the Unicode plaintext disclaimer using the %s encoding." (The “%s” is replaced by the encoding name.)

Appendix E - File types list overview

Appendix G - Backing up and restoring Microsoft Antigen for Exchange