Create an ADF Mapping File

The mapping file is a five-line CSV file that specifies the column names and the field data types for each field in the data file.

The ADF Directory files may also be configured to point to a Comments directory; however, the Comments file is automatically generated by the console.

You can find example map and data files at the following location:

C:\ProgramData\Mitel\MiVoice Business Console\config\Example ADF Files\PBSync

Creating the Mapping File

To create a Mapping file

Use a spreadsheet program to create a blank file.
Enter the mapping data.
1. Use the Example Mapping File to see how your data should appear in the spreadsheet.
2. Use the Mapping File Field Descriptions table for detailed instructions on entering and verifying values in Rows 1 to 4 of the mapping file.
3. Use the Mapping File Data Types Table table to properly tag the data that you entered in Row 4 of the Mapping File spreadsheet. Enter the appropriate Data Tags on Row 5 of the spreadsheet.
Save the file in CSV format with any name you choose. You may wish to use a name that makes the Mapping file easily recognizable: for example, Directory_Mapping.CSV.

You may be prompted to confirm that you wish to save in CSV format.

Note: When you are ready to specify the Directory File names and paths, it is recommended that you save both the Mapping file and the Data file together in the same directory.

Example Mapping File

The Mapping file must contain five lines of information in the order shown in the following example.

Note: The values shown in this example may differ from the values that you enter in your Mapping file. See the Mapping File Field Descriptions table for details about valid values.

File Format Version	5
Data starts on line	2
Prefix Digits	9
Last Name	First Name	Number.	Department	Location	Email	Tel Dir Name	Unique ID	Prime Phone Service	Privacy	Presence
LN	FN	DN	DPT	LOC	PEML	TDN	GUID	PPS	PVY	LCS

Mapping File Field Descriptions

Line	Column 1	Column 2	Column 3	Description
1	File Format Version	2	blank	Enter any comment text in Column 1. You may use the example text (File Format Version) or your own text. Enter a digit in Column 2 (MANDATORY VALUE). Leave all remaining columns blank (no value). Note: User Messaging is enabled with Value 2 or higher. Value 3 or higher allows ADF to be set up to display and distinguish Phonebook entries by colour. Value 4 enables the Multiple Company Directory feature. Value 5 - required for MiVoice Business Console, Release 8.0 to support synchronization with the MiVoice Business Phonebook Directory export.
2	Data starts on line	1 - 100	blank	Enter any comment text in Column 1. You may use the example text (Data starts on line) or your own text. The value in Column 2 depends on the format of the accompanying data file. For example, if data starts on line 1 in the data file, enter the digit 1. If the first line of the data file contains one line of column headers with data starting on line 2, enter the digit 2. Skip any header lines that may be present. Leave all remaining columns blank (no value).
3	Prefix Digits	blank, 9, or other dialing prefix number	blank	Enter any comment text in Column 1. You may use the example text (Prefix Digits) or your own text. Enter the dialing prefix digit(s) (for example, 9, for dialing external calls) in Column 2. Prefix digits apply to all numbers that are tagged to use them. Valid entries may be 0 to 30 characters in length. Leave all remaining columns blank (no value). Note: All numbers that are tagged as PPHN data entries (that is, as prefixed phone numbers: see the Mapping File Data Types Table for a description of the PPHN tag) will be prefixed with the digit(s) in this field. Only one prefix digit value can be applied to the PPHN numbers in your data file. For example, if you dial 9 to reach certain external numbers, and 8t o reach a different subset of external numbers, you may prefer to leave this field blank, enter the prefix digits directly in each entry, and tag all dialable numbers asPHN. Alternately, you could enter the most commonly-used prefix digit in this field, and enter less commonly-used prefixes in specificPHNentries.
4	user-defined column header text (any text)	user-defined column header text (any text)	user-defined column header text (any text)	The text that you enter in Columns 1 to 30 in this row will display as the Phone Book and BLF display field names. For example, you could enter First Name in Column 1, Last Name in Column 2, Extension in Column 3. Enter the column header text in up to 30 columns in this row, one complete, unique column header entry in each cell. Each entry can be up to 100 alphanumeric characters long. See the Mandatory Mapping File Fields table to ensure you capture the minimum requirements for this row. Note: The column header values that you enter in this row must follow the same order as the columns of data in the data file. For example, if Column 1 in the data file contains First Name data, you must enter First Name in Column 1 in the mapping file. Otherwise, the data will not appear under the correct headers and the Directories search operation will not work.
5	user-defined data type tag	user-defined data type tag	user-defined data type tag	The data type tags that you enter in Columns 1 to 30 in this row correspond to the column header text you enter in Row 4. The data type tags tell the console how to interpret the column header values in Row 4. For example, if you entered First Name in Row 4, Column 1, you must enter the tag FN in Row 5, Column 1. Enter the data type tags that correspond to the column headers in Row 4 by referring to Mapping File Data Types table below.

Mapping File Data Types

Note: Values other than those listed in this table cannot be read and are treated as errors.

Data Type Tag (not case-sensitive)	Description
FN	First Name or Full Name Indicates First Name if the data file detects an LN tag in any other cell in the row. Indicates Full Name, if the data file detects no LN tag and no LN value in any other cell in the file. The format for an FN value when interpreted as Full Name must be "Last Name, First Name".
LN	Last Name LN is a mandatory tag if FN is to be interpreted as First Name. LN is an optional tag if FN is to be interpreted as Full Name. If you intend FN to indicate Full Name, the LN field must not be present.
TDN	Telephone Directory Name The TDN field contains the name from the MiVoice Business Telephone Directory and is used as one of the key fields in a synchronization with the MiVoice Business Phone Book.
PPS	Primary Phone Service PPS indicates that this entry corresponds to the Primary Phone Service for a User. The field is part of a MiVoice Business Phone Book Export.
DN	Directory Number (DN) or Extension Valid entries are the digits 0 through 9, plus the letters that correspond to the phone keypad numbers (example, A = 2), *, and #. Letters may be upper- or lower-case.
GUID	Global Unique Identifier If present, this field uniquely identifies records in the file and is treated as a text field. If this field is not present, you must enter an FN, LN, and DN field, which are used in combination to uniquely identify the record in the file. Note: The uniqueness of either the GUID or the FN, LN, DN combination is not verified on import. You must verify their uniqueness within the data file. If a record's GUID or FN, LN and DN combination is not unique, a record may have wrong comments attached to it.
PVY	Private Indicates whether the extension is a private number. If an entry is tagged with PVY, then the icon appears beside the entry. This indicator must match the programming for the corresponding DN in the MiVoice Business. If the data is “Yes” (case insensitive), the Privacy icon will be turned on; any other text will have the privacy icon turned off.
PHN	Dialable Phone or Extension Number Valid entries contain digits 0 through 9, letters that correspond to the phone keypad numbers (example, A = 2), , and #. Letters may be upper- or lower-case. Entries with this tag are dialed exactly as entered. If entries require a prefix (for example, the digit 9, if the call is external), consider using the tag PPHN* as an alternative tag, or enter the prefix as part of the number in PHN fields. For example, 6LAB is dialed as6522, and 95922122 is dialed as prefix (external) 9-5922122.
PPHN	Dialable Phone or Extension Number that is automatically prefixed with the value contained in the Prefix Digits field. For example, if the mapping file Prefix Digits field value is 9, then all numbers tagged with PPHN are prefixed with 9, that is 6135551234 will be dialed as 96135551234. Valid entries contain digits0 through9, plus the letters that correspond to the phone keypad numbers (example, A = 2), *, and #. Letters may be upper- or lower-case. Note: Do not enter an extension number in this field (for example, 5551234x4321). All letters are dialed as the corresponding number on the phone keypad; so therefore the x is dialed as a 9, and the resulting dialing sequence will be incorrect.
DPT	Department Indicates the entry's Department information.
LOC	Location Indicates the entry's information.
TXT	Text Indicates plain text.
EML	Email Indicates a user email address in the format [email protected] (example, [email protected]). Entries must have fewer than 100 characters to be valid. Multiple email columns are allowed. A field tagged as EML appears as an option when the operator clicks a directory entry.
PEML	Phonebook Email The PEML field contains the user email address. The field is part of a MiVoice Business Phone Book Export.
LCS	Live Communication Server or Office Communication Server User Address The LCS column is required only for third-party contacts. It is no longer required to be present in the ADF file in order to enable the MiCollab Client Integration feature. This field needs to be filled in only for third-party contacts. The field must contain the sign-in name string, usually an email address in the format [email protected] (example, [email protected]). Entries must have fewer than 100 characters to be valid. For MiCollab Clients, the field does not need to be filled in. In this case, the MiVoice Business Console automatically synchronizes the MiCollab Client addresses with the MiCollab Client server. If the field is filled in for a MiCollab Client contact, it is ignored. The exception is when the DN of the ADF entry does not match with the MiCollab Client contact DN.
COM	Company Indicator Indicates the entry's Company name. Data marked with this tag is shown in the Company fields (Greeting, Dialed Company, Dialed Number, and Company Comments) of all the panels in the Queued Calls area.
FCLR	Foreground Colour Indicates that the Phonebook entry will display in colour, based on the values entered. The numbers entered correspond to a Red-Green-Blue colour value (RRR-GGG-BBB), where each component colour is a number between 0 and 255; example, 20 200 155 Three values must be entered, with a space between each value. Each value does not need to be three digits, e.g. a value of 20 is acceptable. If one of the values is greater than 255, or if less than three values are entered, the colour will default to black. Tip: You can determine the colour value by selecting a colour using the Microsoft Paint program, available on the Windows platform. When in the Paint program, go to the menu item Colors->Edit Colors, and click on the Define Custom Colors button. Click on a solid colour from the multi-colour region and then vary the intensity using the slider on the right. Make note of the Red/Green/Blue values and enter them into the Mapping File as described above.
IGN	Ignore Enter this value if you want the field to be ignored on import. You may want to tag data with Ignore if you do not want to remove a field completely from the file. Alternately, you can erase the field completely.

Mandatory Mapping File Fields

If you are using Phone Book Directory or Telephone Directory based ADF files, the exported fields from the MiVoice Business should not be modified or removed from your ADF files.

If you are using a Standalone ADF Directory, the following mandatory fields are used to form the key for the BLF list and to match the directory record with the correct entries in the Comments file.

Requirements	FN	LN	DN	GUID
If you wish to use the Global Unique Identifier (GUID) as the unique record key	Optional	Optional	Mandatory	Mandatory
If you wish to use FN as Full Name	Mandatory	Not Allowed	Mandatory	Optional
If you wish to use FN as First Name and LN as Last Name	Mandatory	Mandatory	Mandatory	Optional

↑