LDAP Directory Synchronizer
Online Documentation

HOME NEXT PREVIOUS

Record Description Files

A Record Description File (RDF) is used by LDSU to "map" data in an input file to attributes in the LDAP directory or to define the format of an output file containing LDAP Directory attribute values on an Export.

The RDF contains a series of steps (like a program) which are executed in order by LDSU. There are two types of RDFs: Input and Output.

An Input RDF is used to translate a Input File into a temporary file (called a metafile by LDSU). The metafile contains a single record for each record (which can be multiple lines) in the input_file. This single record contains all the RDN's and ATTR's that are identified in the layout file. An Input RDF, therefore, contains statements which assign values to the RDN and ATTR values.

An Output RDF is used to format Output Files from a metafile. An Output RDF, therefore, contains statements which write values to the Output File.

An RDF may also contain conditional logic which decides what values should be written where based on other values.

An RDF may also contain logic which allows records to be ignored in an input file or not written to an output file.

LDSU RDF Syntax

The format of an RDF statement is one of the following:

action
? conditional : action
? conditional : action : else_action
? conditional : IGNORE

The format of an action (or else-action) clause differs depending on whether the RDF is being used to define an input or output file.

RDF action format for Input Files

When the RDF is used for reading a foreign directory input file, the format of an action (or else_action) clause is:

Destination = Source

The Destination field must be an LDAP Directory attribute which is listed in LDSU_LAYOUT.DAT (as an RDN or ATTR).

The Source field may be one the following:

constant string
Double quoted "Constant String" (e.g. "Digital")
input record location
RECORD_NUMBER.STARTING_COLUMN.WIDTH (e.g 1.1.64)
input record field
RECORD_NUMBER-FIELD_NUMBER(e.g. 1-1)
input record field substring
RECORD_NUMBER-FIELD_NUMBER.STARTING_COLUMN.WIDTH (e.g. 1-1.1.64 or 1-1.10.#)
input record sub-field
RECORD_NUMBER-FIELD_NUMBER-SUBFIELD_NUMBER (e.g. 1-1-1)
input record sub-field substring
RECORD_NUMBER-FIELD_NUMBER-SUBFIELD_NUMBER.STARTING_COLUMN.WIDTH (e.g. 1-1-1.1.64 or 1-1-1.1.#)
keyword
an LDAP attribute in LDSU_LAYOUT.DAT (e.g. surname)
function
an LDSU Function (e.g. $TOUPPER(1-1) ) (see RDF Functions below)

The meaning of the terms used in a input record location or field are:

RECORD_NUMBER
is a number between 1 and the INPUT_LINES_PER_RECORD parameter. Some directory files contain more than one line of information for each subscriber entry (i.e., the data for an individual may be placed on successive lines rather than on the same line). RECORD_NUMBER allows specification of the record number which contains the data to be imported into the LDAP attribute.
STARTING_COLUMN
is the column number in the input foreign directory file where the attribute starts. For an input record field, the column number is the column number relative to the start of the field. Column numbers start at 1.
WIDTH
is the length of the attribute to be read. For example, if a WIDTH of 20 is specified, then LDSU begins reading the location specified by the STARTING_COLUMN parameter and writes the next 20 characters to the indicated attribute in the LDAP Directory. For an input record field, a width of # can be specified to mean the remainder of the field.
FIELD_NUMBER
is the field number from 1 to N between field separator strings. The field separator string is the first string specified by the RDF_FIELD_SEPARATOR parameter in LDSU_CONFIG.DAT.
SUBFIELD_NUMBER
is the sub-field number from 1 to N between sub-field separator strings within a field. The sub-field separator string is the second string specified by the RDF_FIELD_SEPARATOR parameter in LDSU_CONFIG.DAT.

Some examples of Input File Action Lines are:

emailORGNAME = "Sales"  ! constant string
emailSURNAME = 2.1.10   ! 1st 10 characters of line 2
emailGIVENNAME = 1-1    ! 1st field of line 1
emailUSE1 = 1-2.1.10    ! 1st 10 chars of 2nd field of line 1
emailUSE2 = 1-3-2.1.10  ! 1st 10 chars of 2nd sub-field of
                        !   3rd field of line 1
emailUSE3 = 1-3-2.11.#  ! characters 11 until the end of the 2nd 
                        !   sub-field of the 3rd field of line 1
surname = emailSURNAME  ! LDAP Directory keyword
rfc822mailbox = $GSUB(cn," ",".") ! function to replace spaces with dots
rfc822mailbox = "@xyz.com"	  ! and add a constant string

If the same destination keyword is repeated, the source values are concatenated together:

commonName = 1-1        ! These three lines are combined
commonName = " "        !   together to create the value
commonName = 1-2        !   for the commonName attribute

RDF action format for Output Files

When the RDF is used for creating a foreign directory output file, the format of an action (or else_action) clause is:

Source = Destination

The Destination field can be one of two formats:

The Source field may be one the following:

keyword
an LDAP attribute in LDSU_LAYOUT.DAT (e.g. surname)
constant string
Double quoted "Constant String" (e.g. "Digital")
function
an LDSU Function (e.g. $TOUPPER(initials) ) (see RDF Functions below)

The meaning of the terms used in a Output Record Location are:

RECORD_NUMBER
is a number between 1 and the OUTPUT_LINES_PER_RECORD parameter. Some directory files contain more than one line of information for each subscriber entry (i.e., the data for an individual may be placed on successive lines rather than on the same line). RECORD_NUMBER allows specification of the record number that data is to be written to in the output Foreign Directory File.
STARTING_COLUMN
is the starting column number in the output foreign directory file record where data is to be written. the starting column can be specified by the asterisk (*) character, which means "write the next output file data field immediately after the last field written."
WIDTH
is the length of the source data to be written to the output file. For example, if a WIDTH of 20 is specified, the first 20 characters from the source data are written to the export file, beginning at the spot indicated by STARTING_COLUMN. The field length can be expressed by the pound sign (#) character, which uses the length of the data found in the source as the field's width. For LDAP Directory keywords, trailing spaces are truncated.

The Variable Length Field Value (N-*-#) means to write the OUTPUT_FIELD_SEPARATOR character (default: a tab) followed by the source value at the end of Line N. When using this syntax, the first field should use the N.1.# syntax to avoid starting the line with OUTPUT_FIELD_SEPARATOR.

Output Record Location and Variable Length Field Value formats can be interchanged in the same RDF file:

!
! Output:  "MailboxNameSMTP:Address"
!
"Mailbox" = 1.1.#
cn = 1-*-#
"SMTP:" = 1-*-#
rfc822Mailbox = 1.*.#

RDF conditional format

An RDF conditional starts with a question mark (?) character and terminates with a colon (:) character. The question mark can be thought of being an "IF" and the colon a "THEN". (And the second, optional colon an "ELSE").

The conditional logic allows fields to be compared using EQUAL (==), NOT EQUAL (!=), NOT (!), SUBSTRING OF (<<), and NOT A SUBSTRING OF (!<) operators:

? field  == "STRING" :  ! True if field equals STRING
? field1 !=  field2  :  ! True if field1 does not equal field2
? field  << "STRING" :  ! True if field is a substring of STRING
? field  !< "STRING" :  ! True if field not a substring of STRING
? field  :              ! True if field is non-blank
? !field :              ! True if field is blank

Fields used in conditionals can be one of the following:

constant string
Double quoted "Constant String" (e.g. "Digital")
record location
RECORD_NUMBER.STARTING_COLUMN.WIDTH (e.g 1.1.64)
input record field
RECORD_NUMBER-FIELD_NUMBER (e.g. 1-1)
input record field substring
RECORD_NUMBER-FIELD_NUMBER.STARTING_COLUMN.WIDTH (e.g. 1-1.1.64 or 1-1.10.#)
input record sub-field
RECORD_NUMBER-FIELD_NUMBER-SUBFIELD_NUMBER (e.g. 1-1-1)
input record sub-field substring
RECORD_NUMBER-FIELD_NUMBER-SUBFIELD_NUMBER.STARTING_COLUMN.WIDTH (e.g. 1-1-1.1.64 or 1-1-1.1.#)
keyword
an LDAP attribute in LDSU_LAYOUT.DAT (e.g. surname)
function
an LDSU Function (e.g. $TOUPPER(1-1) ) (see RDF Functions below)

All comparisons are case insensitive (e.g. "a" equals "A").

Comparisons can be combined by use of logical AND (&&) and OR (||) operators:

? field == "A" || field == "B" :  ! True if field is A or B
? field != "A" && field != "B" :  ! True if field not A or B
? field << "AB" || field == "E" : ! True if field is a substring
                                  !   of AB or field equals E

Parenthesis can also be used for complex conditionals:

? (field == "A" || (field != "B" && field1 != field2) ) :

The boolean NOT (!) operator can also be used:

? !(field == "A" || field == "B") : ! True if field is not A or B
? !field :                          ! True if field is blank

An optional ELSE conditional statement after a second colon (':') may be specified:

? 1.1.10 : description = 1.1.10 : description = "Default"
instead of having to do:
? 1.1.10 : description = 1.1.10
? !1.1.10 : description = "Default"

RDF IGNORE clause

If a conditional is specifed, the action line can be "IGNORE".

This causes any input record which matched this condition to not be used.

For example, the following will skip any records that contain the substring "admin" in field 2 in the input record.

? "admin" << 1-2 : IGNORE

ADD, MOD, DEL conditionals

The conditional can also contain the reserved words: ADD, MOD, and DEL. These conditionals can be tested to see if LDSU is currently using an ADD, MODIFY, or DELETE input file (for TRANSACTION Mode) or output file (for CHANGES Mode).

For example, the following CHANGES mode output RDF may contain:

? ADD : "Create" = 1.*.#
? MOD : "Modify" = 1.*.#
? DEL : "Delete" = 1.*.#

This allows a single RDF to be used in TRANSACTION and CHANGES mode even thought the Add, Modify, and Delete files need to generate different values.

RDF Functions

RDF Functions can be used to assign a string value. They can be used as:

The following RDF Functions are available:

FunctionDescription
$GSUB(field, "old", "new") subsitute ALL occurences of old to new in field
$SUB(field, "old", "new") sub first occurence of old to new in field
$LSUB(field, "old", "new") sub last occurence of old to new in field
$TOUPPER(field) return field in uppercase
$TOLOWER(field) return field in lowercase
$TOASCII(field) return 7-bit ascii field
$SUBSTR(field, "start", "length") return a subfield. "start" is the starting character in field (1-N). "length" is the number of characters to return (up to end of field).
$DATE("format") return a field in the desired time format. Refer to strftime C function for valid values for "format"
$LENGTH(field) return the length of the field in ascii
$NORMALIZE(field) return the field w/o leading/trailing/multiple spaces
$SYSTEM(command[, arg1, arg2]) run a custom script to get a value
$INDEX(field, "num", "separator") return substring #num(1-N) in field using separator to define substrings. (e.g. $INDEX("A-B-C", "2", "-") would return "B").

Other RDF syntax Rules

Tilde

The Tilde (~) character has a special meaning in TRANSACTION and CHANGES1 mode when comparing records. If the value for an attribute in the input file is set to "~", then the attribute will not be modified in TRANSACTION mode or not considered changed in CHANGES mode.

This is useful when the input file doesn't have the LDAP Directory value for some records and doesn't want to change the value in the Directory (Modify TRANSACTION mode) or cause an change to occur (CHANGES Mode).

For example, in TRANSACTION Mode, a Modify RDF can contain:

? 1-1 == "ABC" : ldapfield = "NEWVALUE" : ldapfield = "~"

This will cause the "ldapfield" to be updated to "NEWVALUE" under certain conditions but will remain unchanged under others.

Comments

RDF comments start with a ! character in column 1.

Line Continuation

RDF lines may be continued on the next line by ending a line with the hypen ('-') character:

? (1-1 == "TEST") || (1-2 != "ORG1" && 1-2 !="ORG2") : -
    organization = "ABCD" : -
    organization = "EFGH"

Maximum Line Length

Each line in a RDF must be less than 256 characters. All continuation lines which form one record must be less than 512 characters combined.

Whitespace

Whitespace characters (space, tab) outside of double quotes are ignored. The above examples usually show tokens separated by a single space character but that is only used for clarity and is not required.


HOME NEXT PREVIOUS

Digital Copyright © Digital Equipment Corporation 1998