APPENDIX C

Maps and Filters



Maps and Filters are two common closely related concepts in directory synchronization, though they may be known by different names in different products. Maps are configurable rules that determine how one or more attributes of one directory are combined to produce an attribute in another directory. Maps are needed for two primary reasons:

Semantics vary: For example, one e-mail directory might include a JOB DESCRIPTION field that contains the same contents held in the TITLE and BUSINESS CATEGORY fields of another directory.
Formats vary: For example, one e-mail directory might allow a description field to contain 500 characters while another directory might limit the same field to 250 characters.
Filters are configurable rules that determine which objects are to be propagated, based on the values of certain attributes. Filters are needed to block propagation of objects which are not relevant to, or not authorized in, other directories. For example, e-mail system administrators typically have two e-mail accounts: a personal e-mail account, used to interact with other users; and an administrator's account used to maintain other accounts on the e-mail system. In most instances it is not necessary, or desirable, to propagate the latter e-mail address to other directories. To avoid this, you can filter it.

Like maps, filters are typically defined separately for each direction. The scalability constraints of many simple e-mail system directories may preclude the blanket propagation of all enterprise users to each of the outlying secondary directories, so in order to limit the size, only objects meeting certain criteria might be propagated. In the other direction, user objects which are only of local interest would likely be filtered out.

Creating Maps and Filters

In most cases, you are not required to write new maps or filters. Rather, you need to modify the settings used in existing filters. To adjust or create maps and filters, you need to use software-specific grammar. These grammar variables are described in xx. Examples are provided for each variable..

TABLE  C-1   Map and Filter Variables
Variable
Description

variable

Variables are of the format "${Variable Name}", although the curly brackets may be omitted if the variable is only one word. Upon the initial processing of a record for import, the variables set are those specific to the channel performing the directory sync. The list of channel variables are found in /etc/opt/SUNWMail/gtw/cfg/<channel.attval. 

X.500 variable names are "friendly" names defined by the browser configuration. 

Temporary variables may be used without declaration and may be read or assigned as needed. These temporary variables will not be in the final output of the record. Variables used for output are those in the canonical list of X.500 attributes (for import, SD-CD) and those in the canonical list of per-channel attributes (for export, SD<-CD). 

Example 1 (cc:Mail) 

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

$Name 

$Addr 

$Cmts 

$Locn 

Example 2 (some X.500) 

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

# These variable names come from the browser config, so as 

# the browser configuration file changes so do these variable names 

$Surname 

${Given Name} 

$Title

match line

A match line is always part of a match construct. The match line is composed of a right-hand side and a left-hand side. All variables and expressions on the left-hand side are interpolated into a text string. This string is then matched against the right-hand side. 

match line (cont)

Each match line is processed using the following rule: 

EXPAND TO THE LEFT, MATCH INTO THE RIGHT 

Example 1 

--------- 

# This match line will always work 

# Constants will always match themselves 

1 : 1 

Example 2 

--------- 

# This match line will never work 

# Constants are not equal to different constants 

2 : 1 

Example 3 

--------- 

# This match will always work as will 

1 : $temp 

Example 4 

--------- 

# This match is typical of what you will see 

$Name : $Surnam, ${Given Name}

match#

The "match" is the main construct used in the mapping file. The first line consists of the word "match", optionally followed by the word "any". There are then one or more match lines, then an optional "assign", "reject", or "foreign" construct. The "match" construct is terminated with a line that contains the word "endmatch".

  • When this construct is processed for a record, each of the match lines are attempted in sequence.

  • If ALL of the match lines succeed, then the "assign", "reject", or "foreign" action occurs.

  • A successful "match" will also have the side effect that all the right hand side variables will be assigned values.

  • If the first line of the "match" is "match any", then the first successful match is used. The rest of the match lines for the "match any" construct will be skipped. This is also a successful "match" and the "assign", "reject", or "foreign" action occur normally.

    • match# (cont)

    MATCH

    $Name : $Surname, ${Given Name}

    ENDMATCH

    # If $Name is "Smith, Bob" the above "match" will map

    # "Smith" to $Surname and "Bob" to ${Given Name}

    Example 2

    ---------

    # This example shows how to assign defaults for your environment

    # Say you want all employees to have the same zip code

    MATCH

    1:1

    # 1 ALWAYS matches 1

    ASSIGN

    ${ZIP Code} = 55555

    ENDMATCH

    Example 3

    ---------

    # This example shows how you could use a "match any" construct to #X.500 attributes

    MATCH ANY

    $Name : $Surname, ${Given Name}

    $Name : ${Given Name} $Surname

    $Name : $Surname

    ENDMATCH

    # If $Name=Smith,Bob, then the first match line will succeed and we #assign "Smith" to $Surname and "Bob" to ${Given Name} If $Name=Bob Smith, then the second match line will succeed and we #assign "Smith" to $Surname and "Bob" to ${Given Name}

    #If $Name=Smith, then the third match line will succeed and we #assign "Smith" to $Surname, but ${Given Name} is still unbound

    assign

    The "assign" construct is used within a "match" to make simple variable assignments after a match is successful. Analogous to the

    match rule of a match line, the assign rule is EXPAND THE RIGHT, ASSIGN TO THE LEFT. 

    assign (cont)

    This means: 

    text on the right-hand side of the "=" is interpolated, and then assigned to the variable on the left-hand side. 

    Assignments do not use regular expressions and the left-hand side may only contain one variable. 

    There may be multiple lines in an assign statement. 

    Example 1 

    --------- 

    # Match a constant to itself to set a default value for 

    # a variable 

    MATCH 

    1:1 

    ASSIGN 

    $Surname:Unknown 

    ENDMATCH 

    Example 2 

    --------- 

    # Use temporary variables to parse the cc:Mail $Cmts 

    # variable and then assign the temporary variables to an 

    # X.500 attribute 

    MATCH 

    $Cmts:$a-$b-$c,$Title 

    ASSIGN 

    $homePhone = $a-$b-$c 

    ENDMATCH 

    # This match succeeds if $Cmts=608-238-4454,President 

    # Now "President" is assigned to $Title and $a = "608" 

    # $b ="238" $c = "4454" the ASSIGN explicitly assigns 

    # "608-238-4454" to ${Home Phone}

    reject

    The "reject" rule is used within a "match" as a means of filtering content. If the match succeeds, the record is ignored. 

    Example 1: 

    ---------- 

    # Filter out all "ADMIN" users, so these entries are not 

    # added to the central directory 

    rejext (cont)

    MATCH 

    $Name:admin.* 

    REJECT 

    ENDMATCH 

    Example 2: 

    ---------- 

    # Filter out any users like "ROOT" or "POSTMASTER" 

    MATCH ANY 

    $Surname : Root.* 

    $Surname : Postmaster.* 

    REJECT 

    ENDMATCH

    foreign

    The "foreign" construct is used to remove foreign entries. When foreign entries are being stored this construct saves the matched record as a foreign entry. Most foreign entries have very specific rules to match them according to the channel that is performing directory sync. 

    Example 1 (cc:Mail) 

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

    MATCH 

    $Addr:GATEWAYPO.* 

    FOREIGN 

    ENDMATCH 

    Example 2 (MSMail) 

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

    MATCH 

    $MSAddress:SMTP.* 

    FOREIGN 

    ENDMATCH 

    Example 3 (PROFS) 

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

    MATCH 

    $NODE:GATEWAY 

    FOREIGN 

    ENDMATCH 

    Functions

    Use functions in the interpolated sections of a "match" or "assign" to modify a variable. You may not nest functions (but you can certainly use a temporary variable to get the same effect), and there is no way to define a new function.

    Descriptions for each function are provided in TABLE C-2.

    TABLE  C-2   Function Descriptions
    Function
    		 Synopsis
    		 Description

    field

    &field(<variable, <field, <delimiter)

    Return field number <field delimited by <delimiter from <variable

    Arguments:  

    <variable is a bound variable name 

    <field field number to extract from <variable, fields are indexed starting at 1 (one) 

    <delimiter string to use as delimiter to split <variable

    Example:  

    If $Addr=CCPOST field2 field3 &field($Addr, 1, " ") this returns "CCPOST"

    subsrt

    &substr(<variable, <offset, <length)

    Extract a string of <length> from <variable> starting from the

    offset

    &offset(<variable, <length)

    <offset> position in <variable>

    Arguments

    <variable> is a bound name

    <offset> Starting position for substring. The first character of a string is offset 0 (zero). If the offset is a negative number, this will begin substr in the back of the string. - l is the last character.

    <length> Length of string to be returned,

    Returns:  

    String equal to or less than <length

    Example:  

    if $Surname=Anderson $substr($Surname, 0, 6) this will return "Anders"

    length

    &length(<variable)

    Return the number of characters in a string.

    Arguments:  

    <variable - is a bound variable name

    Returns: Number of characters in a string assigned to <variable

    Example: if $Cmts="hello" &length($Cmts) 

    this returns 5

    expand

    &expand(<variable)

    Expand contents of <variable if any parts match the set of predefined values found in the directory sync configuration.

    Arguments: <variable is a bound variable name

    Returns: Expanded string

    Example:  

    if $Title = V.P. Eng. &expand($Title) 

    This returns "Vice-President Engineering"

    Configuration:  
    The expand function maps the abbreviation that users have configured through the modification to /etc/opt/SUNWMail/gtw/cfg/<channel.attrname.

    abbrev

    &abbrev(<variable)

    Abbreviate contents of <variable> if any parts match the set of predefined values found in the directory sync configuration.

    Arguments: <variable> is a bound name

    Returns: abbreviated string

    Example: If $Title = Vice-President Engineering &abbrev($Title) 

    This returns "V.P. Eng."

    Configuration:  

    The abbrev function maps the abbreviation that users have configured through the  the modification to /etc/opt/SUNWMail/gtw/cfg/<channel.attrval.

    Expressions

    Expressions are simple comparisons that may be performed within a match to check for a valid string. They are set off by use of square brackets. The following things may be used in an expression: variables, functions, string and numeric constants, string relational operators (eq, ne, lt, gt, le, ge), numeric relational operators (==, !=, <, ,<=, =), the string concatenation operator (.), the unary negation operator (-), the logical operators (not, and, or), and the ascii-to-character and character-to-ascii converter functions (ord, chr).

    Example:

    match

    $a $b $c $d $e: ${Hope this is long enough}

    [&length($Hope this is long enough} < 123]

    assign

    ${Real variable} = ${Hope this is long enough}

    endmatch



    Copyright © 1999 Sun Microsystems, Inc. All Rights Reserved.