INTERNAL – Authorized for SAP Customers and Partners SAP NetWeaver Master Data Management 7.1
Document Version: SP20 – May 2019
MDM Syndicator
AP affiliate company. All rights reserved.
Content
1 MDM Syndicator Reference Guide. . . . 4
1.1 Basic Steps to Using MDM Syndicator. . . 4
Starting and Connecting to a Repository. . . 5
MDM Syndicator Main Window. . . .8
1.2 Managing Map Files. . . .10
Syndication Maps. . . 10
Creating a New Syndication Map. . . 11
Opening Maps. . . .12
Deleting Maps. . . 13
Exporting Map Files. . . 14
Importing Map Files. . . .14
Making a Map Available to Other Remote Systems. . . .15
XML Schema Enforcement in Syndicator. . . 15
Editing Map Properties. . . 17
1.3 Preparing Source Items. . . .23
The Source Items Grid. . . .24
Additional Source Items. . . .26
1.4 Preparing Destination Items. . . .35
Destination Items Grid. . . .35
Customizing Destination Item Values. . . .39
Destination Item Property Inheritance. . . .43
1.5 Mapping Items. . . .49
Mapping and Unmapping Items. . . 49
Mapping and Unmapping Items on Flat Maps. . . 51
Mapping and Unmapping Items on XML Maps. . . 52
Mapping Lookup Table Data. . . 52
Mapping Multi-Valued Fields. . . .53
Mapping Qualified Data. . . 56
Mapping Tuples. . . .60
Mapping Hierarchy Fields. . . .64
Mapping Multilingual Fields and Attributes. . . .73
Mapping Remote Keys. . . 77
Mapping Personal Data Indications. . . 79
Mapping Objects. . . .79
1.6 Syndicating Records. . . .80
Selecting Records to Syndicate. . . .80
Suppressing Unchanged Records. . . 81
Previewing the Syndication File. . . .82
Executing Syndications. . . 82
Customizing XML File Syndication. . . .83
Syndicating Checked Out Records. . . .84
1 MDM Syndicator Reference Guide
MDM Syndicator Reference Guide explains how to start and stop Syndicator, describes the Syndicator interface, and provides the basic steps required to syndicate records from an MDM repository.
MDM Syndicator is a tool for creating maps, which extract and transform record data from an MDM repository and save it to text or XML files for later loading into a destination system. You can use these maps to manually export records from within Syndicator, or to run automatic exports with the Master Data Syndication Server (MDSS).
For more information about installing and working with MDM, see the MDM documentation on the SAP Help Portal.
For more information about MDSS, see the chapter, MDSS Administration in the MDM Console Reference Guide.
Related Information
MDM documentation homepage on SAP Help Portal
1.1 Basic Steps to Using MDM Syndicator
Context
There are four basic steps to using Syndicator to extract and transform data from an MDM repository.
Procedure
1. Connect to a Source MDM Repository
When you start Syndicator, you must connect to an MDM repository before doing anything else. The repository you select at start-up serves as the source of all syndication maps created and/or executed during the Syndicator session.
For more information, see Starting and Connecting to a Repository linked below.
2. Define the Map
Syndication maps specify what source data is going to be exported, which remote system is going to receive the syndicated data, and how the data will be formatted when it gets there.
For more information, see Syndication Maps linked below.
3. Select the Records to Syndicate
Syndicator syndicates all records in the Records pane. To limit the set of records included in a syndication file, you can use the Syndicator search and suppress features.
For more information, see Selecting Records to Syndicate linked below.
4. Execute the Syndication
Once you execute a syndication, Syndicator prompts you for the file name and location where you want the syndicated records to be saved (if you are syndicating to a port, the name and location are provided automatically).
For more information, see Executing Syndications linked below.
Related Information
Starting and Connecting to a Repository [page 5]
Syndication Maps [page 10]
Selecting Records to Syndicate [page 80]
Executing Syndications [page 82]
1.1.1 Starting and Connecting to a Repository
A repository must be running in order for Syndicator to connect to it.
You can connect Syndicator to a repository using either an encrypted (SSL) or unencrypted connection, based on the listening mode of the Master Data Server on which the repository is mounted. For more information, see chapter Network and Communication Security in the MDM 7.1 Security Guide.
1.1.1.1 Starting Syndicator
Context
To start Syndicator and connect to a repository:
Procedure
1. Double-click the MDM Syndicator icon.
2. In the Connect to MDM Repository dialog, select the desired MDM repository, the language layer to work in, and enter your user name and password.
Note
If an MDM repository does not appear in the list, you must add it by clicking Browse to set up the connection.
Note
If a repository’s TCP/IP port number changes, you must re-add the repository as the old entry will load whatever repository is loaded on the old TCP/IP port.
Note
The language selected in the Connect to MDM Repository dialog serves as the language layer from which data is displayed in the Records pane and syndicated from during the Syndicator session. MDM displays the current language in the title bar after the MDM repository name.
3. Click OK to connect Syndicator to the repository.
1.1.1.2 Setting Up Unencrytped Repository Connections
Context
To set up an unencrypted connection to an MDM repository:
Procedure
1. In the Connect to MDM Repository dialog, click Browse.
2. In the Choose Repository dialog, select the Master Data Server on which the repository is running.
If the Master Data Server has not been previously connected to by Syndicator, type the name or IP address of its host, or click Browse to select it from a list.
Note
If the Master Data Server is configured to listen on non-"MDM default" ports, you must type in the port number after the Master Data Server name, using the format <ServerName:PortNumber> (for example, ServerXYZ:54321). Otherwise, Syndicator will be unable to connect to the Master Data Server.
3. Select the repository (you may have to click the Refresh button next to the Repository field to load the repository names).
4. Click OK to add the repository to the Connect to MDM Repository list.
1.1.1.3 Setting Up Secure Repository Connections
Context
To set up a secure connection to an MDM repository:
Procedure
1. In the Connect to MDM Repository dialog, click Browse.
2. In the Choose Repository dialog:
a. Select the SSL-enabled Master Data Server.
b. Click Secure Connection.
c. Enter the paths to the client Key File and SSL Library.
3. Click the Refresh button next to the Repository field and choose the repository you want to connect securely to.
4. Click OK to add the repository to the Connect to MDM Repository list.
5. In the Connect to Repository dialog, a lock icon similar to the one shown below indicates that communications with the selected repository will be established on a secure connection.
1.1.2 MDM Syndicator Main Window
The main window of Syndicator consists of the panes and tabs shown in the numbered callouts of the following figure:
1. Search Parameters pane 2. Records pane
3. Tabs pane 4. Status bar
The Search Parameters and Records panes are used to identify which records are to be syndicated, but most of the work in creating syndication maps is performed in the tabs pane.
1.1.2.1 Search Parameters Pane
You can use the search parameters pane to narrow down the set of records in the Records pane to just those you want to syndicate.
Related Information
Selecting Records to Syndicate [page 80]
1.1.2.2 Records Pane
The Records pane displays the current table’s records in a grid, with a row for each source record and a column for each source field. Records shown in this pane will be included in a syndication file, subject to suppression options in the Map Properties tab. The columns appearing in the pane are for display purposes only and do not affect which fields are included in a syndication file.
Note
The maximum number of unique values that MDM can display in a single cell is hardcoded to 20. If the number of unique values for a field exceeds this limit , MDM Syndicator will display the first 20 unique values only and then display ... after the 20th value. However, if the field is mapped, all of its values will be included in the syndication, despite the limited display on the Records pane.
1.1.2.3 Status Bar
The status bar displays information regarding the number of destination items on the current map and the number of records returned by current search selections.
● <x> of <y> mapped (where <x> is the number of destination items on the current map that have been mapped to source items, and <y> is the total number of destination items)
● <x> of <y> records found (where <x> is the number of records on the current table which match the current search selection criteria, and <y> is the total number of records)
Also, when you select a menu command, a brief description of the command is displayed on the status bar.
1.2 Managing Map Files
This section provides instructions for performing basic map operations in Syndicator. It also describes map properties.
1.2.1 Syndication Maps
Syndication maps tell MDM which records to syndicate and how those records should appear in the syndication file. All syndication maps are saved with the repository itself for easy reuse by other Syndicator users or MDSS.
Syndication Map Components
Setting Description
Item Mappings Item mappings tell MDM which source fields to export to
which destination fields.
Search Selections Search selections limit the number of records to export to those which match the search criteria. When you open the map, the saved search selections are automatically applied to the current table records.
Map Properties Map properties are global settings which control the map’s
output format, which remote system keys to include, and op
tions such as the date, currency, and delimiter formatting to apply to record values.
Source Field Transformations You can customize the available source fields to meet the specific needs of the map’s intended destination schema.
These transformations are saved with the map rather than affecting the source data itself.
Destination Items Destination items represent the schema of the map’s inte
dended destination. For XML-based maps, the schema is preloaded based on the map’s associated XML schema. For flat text maps, the destination items are created within Syn
dicator. Destination item properties let you apply field-spe- cific transformations to the values of the mapped source field.
Current Table The current table indicates which repository table to export
records from.
1.2.2 Creating a New Syndication Map
Context
To create a new syndication map:
Procedure
1. Choose File New… from the main menu to open the New Map Properties dialog.
2. In the Type box, select the map type from the drop-down list.
3. Fill in the map properties that correspond to the selected type.
Map properties are described in section New Map Properties linked below.
4. Click OK.
Related Information
New Map Properties [page 11]
1.2.2.1 New Map Properties
The following table describes the map properties that you fill in when creating a new table. The properties depend on the map type.
New Map Properties
Type Description
Property Flat XML Schema XML Schema File Port
Remote System ● ● ● ● The target remote
system for the map.
For more informa
tion about remote systems, see Map
ping Remote Keys linked below.
Port ● The map will only syndicate records to this port.
XML schema* ● The XML schema
used to define the map’s destination items.
XML file name** ● The external XML
schema file used to define the map’s destination items.
Namespace ● ● The root elements
available for selec
tion in the Root property are fil- tered by the se
lected Name
space.
Root ● ● The root element
for the map’s des
tination items.
* Use for XML schemas which have been saved to the repository using MDM Console
** Use for XML schema files located on your external file system
Related Information
Mapping Remote Keys [page 77]
1.2.3 Opening Maps
Context
Only one map can be open at a time in Syndicator.
To open a map:
Procedure
1. To open the Open Map dialog, choose File Open . 2. In the Remote System list, select the map’s remote system.
3. In the Available Maps list, select the map to open.
4. Click OK.
The selected map is now the current map.
Note
Syndicator does not display source or destination items that exist on the map but not on the current table or XML schema.
1.2.4 Deleting Maps
Context
Deleting maps permanently removes them from the repository.
To delete a map:
Procedure
1. To open the Delete Maps dialog, choose File Delete… . 2. In the Available Maps list, select the maps you want to delete.
3. Click Add.
The selected maps now appear in the Maps to Delete list.
4. Click OK.
The selected maps are now deleted from the repository.
1.2.5 Exporting Map Files
Context
The File Save and File Save As options save syndication maps to the repository only. To save a map to an external file, use File Export .
To export a map:
Procedure
1. To open a Save As dialog, choose File Export… .
2. Browse to the location where you want the map file to be saved.
3. In the File Name box, enter a name for the map file and save it as .syn file.
Caution
Do not save the map as an .xml file, as the underlying XML schema definition may be changed in the future. Also, directly modifying the contents of an XML map file may result in the file being unloadable.
4. Click OK.
The map file is saved to the specified location.
1.2.6 Importing Map Files
Context
To import a syndication map file:
Procedure
1. To open an Open dialog, choose File Import… . 2. Browse to the syndication map file and click OK.
Syndicator now reflects the imported map.
1.2.7 Making a Map Available to Other Remote Systems
Context
Saving copies of a map to different remote systems spares you from having to recreate the same map for each of your remote systems.
To save a map to a different remote system:
Procedure
1. To save any changes to the current map, choose File Save . 2. To open the Save As dialog, choose File Save As… .
3. Select a new remote system to save a copy of the map to.
4. Enter the name which the new map will appear as under the new remote system.
5. Click OK.
The new map is now the current map.
1.2.8 XML Schema Enforcement in Syndicator
When loading a map’s XML schema, Syndicator reads the structure of the elements and attributes contained in the schema and reflects this structure in the XML trees displayed in the Item Mapping, Destination Items, and Destination Preview tabs.
Note
Currently, Syndicator only supports a very basic subset of XML schema options. Some options, including xsd:choice and xsd:union, may cause a schema to be rejected outright while others are simply ignored.
Although it is common for additional element and attribute properties (such as datatype restrictions and default values) to be included in an XML schema, the only properties and values which Syndicator actually uses to define destination items are:
● name
● minOccurs
● maxOccurs
● mixed="true"
The values of these properties are displayed in the Syndicator Destination Items tab, as described in Table XML Schema Properties Displayed in Syndicator, and reflected in the item’s name and icon in the Item Mapping tab, as described in Table Element and Attribute Icons in the Destination Items Grid.
XML Schema Properties Displayed in Syndicator
XML Schema Property Destination Item Property
name Name
minOccurs XML Required
maxOccurs XML Repeatable
Note
MDM interprets minOccurs values of >1 as indicating "required" and maxOccurs values of "unbounded" or
>1 as indicating "repeatable".
On the Destination Items grid of the Item Mapping tab, Syndicator displays descriptive icons before each element or attribute name. These icons make it easy for users to “match” destination items to source items during the mapping process.
Element and Attribute Icons in the Destination Items Grid
Icon Description
Childless, non-repeatable element or attribute Repeatable element containing child elements
● Element containing property mixed="true" in the XML schema –or–
● Childless, repeatable element or attribute Non-repeatable element containing child elements
Finally, Syndicator italicizes the names of required items on the Destination Item grid of the Item Mapping tab, making it easy to identify which items will always included in the syndication file.
XML Namespaces
If the targetNamespace attribute is missing in an XML schema, the target namespace is considered empty.
Root elements are always associated with the namespace value found in the targetNamespace attribute.
All other destination items are associated with the targetNamespace value if their form attribute value is qualified, or, if their form attribute is missing, their FormDefault value is qualified.
Note
If multiple namespaces are available, the target namespace to use must be selected when the map is created or an Update XML Schema operation is performed.
1.2.8.1 Updating the XML Schema of a Map
Context
Syndicator uses the XML schema associated with an XML map to define the destination items available on that map. If changes are made to the XML schema after a map has been created, or if you wish to use a different XML schema with the map, you can use the Update XML Schema operation to reload the XML schema into the map.
To update or switch the XML schema of a map:
Procedure
1. Choose File Update XML Schema… from the main menu (map must be in an unmodified state for this option to be enabled).
2. Choose the new or updated XML schema and its related properties.
Syndicator refreshes the Destination Items tree of the map with the information contained in the selected XML schema.
Note
Existing destination items and mappings may change or disappear according to the new XML schema.
Syndicator displays warnings and enters log messages in these cases.
1.2.9 Editing Map Properties
Context
The Map Properties tab displays a list of properties which apply to the syndication files generated by the current map. Not all map properties apply to all maps – some properties are enabled only for XML maps, others only for flat text maps.
To edit map properties:
Procedure
1. On the Map Properties tab, edit property values.
2. To reset a property to its factory default value, in the Reset column click the checkbox corresponding to the property that you want to reset.
Syndicator resets the value to its factory default value and updates the Reset column checkbox from unchecked ( ) to checked ( ).
3. To cancel property changes, right-click and choose Restore to restore the last saved map values.
4. To save map property changes, press Shift + Enter or right-click and choose Save Map Properties.
1.2.9.1 Map Properties
Read-only properties appear grayed out, as do properties that are not available for the current map type (XML or Flat). Default property values appear in bold.
Note
Remote System and Format properties are defined at the time the map is created.
Map Properties Columns
Column Description
Name The name of the map property
Reset Whether not the property is set to its “factory default” value
● - property is set to its default value
● - property is not set to its default value
● - property has no default value
Value The current value of the map property
● Values in gray are inherited from the factory default set
tings
● Values with a light-blue background have been modified but not saved
Map Properties
Flat XML Property Description
● ● Remote System The remote system of the map.
Flat XML Property Description
● ● Format The format of syndication files gener
ated from the map (flat or XML)
● Namespace The XML schema namespace
● Must be 255 characters or less
● For more information, see XML Namespaces in section XML Schema Enforcement in Syndi
cator linked below.
● XML File Output The number of files to generate when
a syndication is executed
● One output record per file
● All output records in one file
● For more information, see Cus
tomizing XML File Syndication linked below.
● Repeating Record Node The name of the record element in
the XML schema
● ● Max Records Per Output File The maximum number of records to
include in an XML syndication file, af
ter which a new file is created. 0 = no limit.
● For more information, see Cus
tomizing XML File Syndication linked below.
● ● Include UNICODE Byte Order Mark Prepends UTF-8 byte order mark to
the beginning of the syndication file.*
● Include Item Names Adds names of destination items as
column headers in the syndication file
● If Item Format is Name/Value Pairs, item names are pre
pended to each item value in
stead of added as column head
ers
● Item Format The format of items in flat syndica
tion files:
● Fixed Width
● Variable Width
● Name/Value Pairs
Flat XML Property Description
● Item Delimiter Character used to separate destina
tion item values when Item Format is Variable-Width:
● Tab
● ,
● ;
● ¦ ( Alt + 0 + 1 + 6 + 6
● | ( Alt Gr + ¦ )
● Custom
● Custom Delimiter Item delimiter used when Item De
limiter is Custom
● Name/Value Separator Delimiter used to separate destina
tion item names and values when Item Format is Name/Value Pairs:
● Tab
● ,
● ;
● ¦ ( Alt + 0 + 1 + 6 + 6
● | ( Alt Gr + ¦ )
● Custom
● Custom Separator Name/Value Separator used when
Name/Value Separator is Custom
● Name/Value Terminator Delimiter used to separate destina
tion items when Item Format is Name/Value Pairs:
● Tab
● ,
● ;
● ¦ ( Alt + 0 + 1 + 6 + 6
● | ( Alt Gr + ¦ )
● Custom
● Custom Terminator Terminator used when Name/ Value
Terminator is Custom
Flat XML Property Description
● Language Format How values from the source item
Language appear in the syndication file:
● 2-Letter Language Code
● 3-Letter Language Code
● Country Code
● Region Code**
● ● Date Format Date format used for data from
source items of type Literal Date and
<date> tokens in a custom item:
● YYYY:MM:DD:HH:MM:SS:MSS
● YYYYMMDD
● MM/DD/YYYY
● DD.MM.YYYY
● YYYY-MM-DD
● ● Timestamp Format Format used for create/change time
stamp fields:
● Internal outputs dates in the for
mat mm/dd/yyyy hh:mm:ss GMT
● .XML dateTime outputs dates in the XML-valid format yyyy- mm-ddThh:mm:ssZ, where
<T> denotes the beginning of the time.
● ● Numeric Decimal Symbol Decimal symbol used for data from
source items of type Currency, Meas
urement, Real, or Numeric:
● .
● ,
● ● Numeric Thousand Separator Thousand symbol used for data from
source items of type Currency, Meas
urement, Real, or Numeric:
● ,
● .
● None
● Space
Flat XML Property Description
● ● Use Currency Symbol For currency fields, includes a cur
rency symbol as part of the field value. The symbol used is defined for the currency field in MDM Console.
● ● Suppress Unchanged Records Excludes records from syndication
which have not changed since the last time they were syndicated to a port or remote system
● For more information, see Sup
pressing Unchanged Records linked below.
● ● Suppress Records Without Key Excludes records from syndication
when they possess no key mapping for the destination or overriding re
mote system
● For more information, see Sup
pressing Unchanged Records linked below.
● ● Remote Key Override Adds a separate copy of each record
to the syndication file for every re
mote system listed
● For more information, see Re
mote System and Remote Key Override linked below.
● ● Filter Multi-Valued Lookup Fields Excludes values which do not match
selections made in the search pa
rameter pane
● For more information, see Filter
ing Multi-Valued Lookup Fields linked below.
● ● Filter Qualified Links Excludes qualified links which do not
match selections made in the search parameter pane
● For more information, see Filter
ing Qualified Links linked below.
● ● Multilingual Fields This property is not editable.
Flat XML Property Description
● ● Language Inheritance The level of language inheritance to
apply to mapped multilingual items:
● None
● Primary
● Secondary
● For more information, see Map
ping Multilingual Fields and At
tributes linked below.
● Suppress Empty Language/Value Pairs Excludes syndication of a language/
value pair when the language has no corresponding value
For more information, see Mapping Multilingual Fields and Attributes linked below.
* Regardless of setting, all syndication files are UTF-8 encoded.
** An internal MDM code
Related Information
XML Schema Enforcement in Syndicator [page 15]
Customizing XML File Syndication [page 83]
Suppressing Unchanged Records [page 81]
Remote System and Remote Key Override [page 78]
Filtering Multi-Valued Lookup Fields [page 56]
Filtering Qualified Links [page 59]
Mapping Multilingual Fields and Attributes [page 73]
1.3 Preparing Source Items
This part of the reference guide describes the Source Items grid and explains how to customize the list of source items available for mapping.
1.3.1 The Source Items Grid
Located on the Item Mapping tab, the Source Items grid displays a tree containing all of the source items available on the current table for mapping.
The root of the tree is the name of the current table. First-level nodes on the tree can include:
● Fields from the current table
● Clone items created from the current table’s fields
● Split items created from the current table’s fields (or their clones)
● Custom items created in Syndicator for use with the current map
● Merge items created in Syndicator for use with the current map
● Attribute collections from the current table
● Remote Key (if enabled) for the current table’s records
Note
For more information about clone custom, and merge items, see chapter Additional Source Items linked below. For more information about splitting and mappping multi-valued, multilingual, and hierarchy source fields, see chapter Mapping Items linked below.
A + next to a tree node indicates an additional branch (level) of tree nodes is available for this item. The type of nodes present on a branch is determined by the data type of the parent item.
The following table describes the branch nodes available for each parent item data type:
Source Item Branch Node Descriptions
Data Type of Parent Item Branch Node Description
Attributes [All Attributes] Placeholder items for the name, value, and remote key of each attribute belonging to a syndicated record
Attributes [Attributes] Every attribute available on the current table
Lookup [<type>]* The fields of the table which the source item looks into to get its value
Merged Source The fields merged from the item’s external source file
Multilingual Item Split By Value Placeholder items for the data values and languages of the multilingual item
Remote Key Placeholder items for the remote system and key values in a
record’s remote key mapping
* <type> is the table type of the lookup table.
All tree nodes appear in the <Name> column of the Source Items grid. The Name column, along with the other columns of the Source Items grid, is described in the following table:
Source Items Grid Columns
Column Value Description
Name* Name The name of the source item
Name [Clone] Item is a clone item
Name [DF] Item is a display field
Name [Hierarchy Position] Item is a split hierarchy item
Name [Language] Item is a multilingual item split by language Name [n] Item is a split multi-valued item (<n> is the or
der position represented by the item) Name [Split] Item is a multi-valued item split by value
<[Language]> Item is a placeholder for the language value of
a multilingual item split by value
<[Name]> Item is a placeholder for attribute names
<[Remote Key]> Item is a placeholder for the key value of a re
mote key mapping
<[Text Value Remote Key]> Item is a placeholder for the key value of a re
mote key mapping
<[Value]> Item is a placeholder for the data values of the
source item
<[Default]> Item is a placeholder for the value of the de
fault remote key flag
Type** Type The data type of the item
Type (multi-valued) Item contains multiple delimited values Text <[x]> <x> = the character width of the field
Custom Item created on the Custom Items tab
Merged Field Field merged from an external table
Merged Source Item created on the Merge Items tab
Mapped <empty> The source item is not mapped
The source item is mapped
Destination Name The name of the destination item mapped to
the source item
* Name of the original field
** Data type of the original field
Related Information
Additional Source Items [page 26]
Mapping Items [page 49]
1.3.2 Additional Source Items
If a destination system has a different schema than your MDM repository, you can transform existing source fields on the Source Items grid (and even add new ones) from within Syndicator to better match the destination items. These changes are saved only to the syndication map and do not affect the original source values in the MDM repsoitory.
1.3.2.1 Creating a Custom Item
Context
Custom items are user-designed source items that can be mapped to any destination item. A custom item can include any combination of:
● Source fields from the current table
● Source attributes from the connected repository
● Remote keys from the current table and its subtables
● Raw text entered directly into the custom item
● Repository name from which the syndicated data originated
● Date and time of the syndication
Custom items are visible as source items on the Item Mapping tab but are created and maintained from the Custom Items tab.
To create a custom item:
Procedure
1. On the Custom Items tab, right-click in the Custom Items pane and choose Add Custom Item.
2. Syndicator adds a new custom item to the Custom Items pane.
3. Enter a name for the new custom item (optional).
4. In the Properties grid, double-click in the Value cell of the Formula property.
5. Click the right-arrow button in the Value cell and choose an item to add to the Value field.
6. To add more items to the formula, repeat steps 5 and 6.
7. To add text to the formula, click in the Value cell to put the cursor where you want the text to appear, then type the text in the cell.
8. Press Shift + Enter to save the custom item.
Results
The custom item now appears in the Source Items grid.
1.3.2.2 Renaming a Custom Item
Context
To rename a custom item:
Procedure
1. On the Custom Items tab, right-click on the custom item you want to rename and choose Rename Custom Item.
2. Type the new name you want for the item and press Enter. 3. Press Shift + Enter to save the name change.
1.3.2.3 Formatting Custom Item Values
Context
You can format custom item values.
Procedure
1. On the Custom Items tab, select the custom item you want to format.
2. Double-click in the formula’s Value cell to open it for editing.
3. Right-click on the item value you want to format and choose a formatting option. Repeat until all formatting is complete.
Formatting options are applied to the selected formula item only.
Note
Only fields, attributes, and remote keys can be formatted. Text entries as well as date, time, and repository values are ineligible for formatting.
4. Press Shift + Enter to save the custom item.
1.3.2.3.1 Custom Item Formatting Options
The default format for a formula item added to a custom item value is:
<ITEM NAME: item name>
where:
● <ITEM NAME> is the name of the formula item.
● <item name> represents the data value of the formula item.
● : is the separator.
Once you add an item to the formula, you can customize it in a variety of ways.
Custom Item Formatting Options
Option Description
Include Name and Value Puts the name of the formula item before its value.
Include Name Only Includes the name of the formula item only.
Include Value Only Includes the data values of the formula item only.
Preserve NULL Value Syndicates all NULL values found in the formula item. (The default action is to skip NULL values.)
Separator… Sets the character that separates the formula item’s name
from its value.
Terminator… Sets the character that marks the end of the formula item.
Suppress Below Withholds attributes with priority levels below the level se
lected here.
Sort Sorts the list of fields or attributes.
Reset Restores the formula item to its default formatting.
The following table shows the results of some basic formatting options:
Results of Basic Formatting Options
Option Formula Item Syndicated Value
Include Name and Value <CATEGORY>: <category> Category: Printers
Include Name Only <CATEGORY> Category
Include Value Only <category> Printers
1.3.2.4 Adding Fields from External Tables
Merge items are user-defined source items which link to tables outside the connected MDM repository. Fields from these external tables can then be mapped directly to any destination item on your map.
Consider the tables Manufacturers and Products. The Products table is part of the MDM repository but the Manufacturers table is located on an external file. Each product record in the Products table contains a manufacturer ID but no manufacturer name, which is contained in the Manufacturers table for each manufacturer record.
External table containing mergeable record data: Manufacturers
NAME CODE CNTR
Weiler 2011 USA
Radnor 1212 UK
CGW 2044 FRANCE
Ekko 5012 JAPAN
External table containing mergeable record data: Products
Item ... Man ID
101 ... 2011
102 ... 2011
103 ... 5124
In order to map record data from the Manufacturers table to destination items in the syndication file, you must merge its fields with the Products table using the Merge Items command.
This command adds a new source item to the Source Items grid whose children are fields you select from the external table, as illustrated in the following figure:
1.3.2.4.1 Adding a Merge Item
Context
Merge items are visible as source items on the Item Mapping tab but are created and maintained from the Merge Items tab.
To add a merge item:
Procedure
1. On the Merge Items tab, right-click in the Merge Items pane and choose Add Merge Item.
2. Enter a name for the new item.
3. In the Source File property, click in the Value field and then click the … button to display an Open dialog.
4. Browse to the location of the merge file and click Open.
Syndicator displays the name of the selected file in the Source File property.
Note
Only tab-delimited files may be used as source files.
5. In the Matching Fields property, click in the Value field and then click the down-arrow to open a field matching table.
6. Select an external table field in the Source Fields column that can be used as a key with the current table of Syndicator.
7. In the Matching MDM Field column of the selected source field, click the down-arrow button to open a list of fields from the current repository table.
8. Select a current table field to match the source field and press Enter.
9. Click the up-arrow button at the right edge of the Value field of the Matching Fields property to close the field matching table.
10. In the Source Fields to Merge property, click in the Value field and then click the down-arrow button to open a list containing the fields from the external table.
11. Add fields to the Merge fields list. Fields selected become individually mappable children of the merge item.
12. Click the up-arrow button at the right edge of the Value field of the Source Fields to Merge property to close the drop-down list.
13. Press Shift + Enter to save the merge item. The merge item now appears in the Source Items grid on the Item Mapping tab.
1.3.2.4.2 Renaming a Merge Item
Context
To rename a merge item:
Procedure
1. On the Merge Items tab, right-click on the merge item you want to rename and choose Rename Merge Item.
2. Syndicator highlights the item name for editing. Type the new name you want for the item and press Enter.
3. Press Shift + Enter to save the name change.
1.3.2.5 Copies of Current Table Items
You can create copies of most items on the Source Items grid, which allows you to perform multiple operations on a single current table field or attribute, such as: (1) mapping it to more than one destination item; or (2) mapping it to one destination item and also splitting it into multiple source items. Copied items contain the same data values as their original.
Note
When you want to both copy and split an original source field, copy first, then split.
1.3.2.5.1 Copying Original Source Field from Current Table
Context
To copy an original source field from the current table:
Procedure
1. On the Item Mapping tab, right-click the current table source field you want to duplicate.
2. From the context menu, choose Clone Source Item.
3. Syndicator adds the clone item below the original source item. The naming format of the clone item is
<original item name[Clone]>.
Only source items originating as fields on the current table can be cloned. Items which are ineligible for cloning have the Clone Source Item option disabled.
1.3.2.5.2 Copying a Custom Item
Context
To copy a custom item:
Procedure
● On the Custom Items tab, right-click on the custom item you want to duplicate and choose Duplicate Custom Item.
Syndicator adds a new custom item, named Copyof<ItemName>, to the Custom Items pane as well as the Source Items grid on the Item Mapping tab. The new item contains the same formula as its original.
1.3.2.5.3 Copying a Merge Item
Context
To copy a merge item:
Procedure
● On the Merge Items tab, right-click on the merge item you want to duplicate and choose Duplicate Merge Item.
Syndicator adds a new merge item, named Copyof<ItemName>, to the Merge Items pane as well as the Source Items grid on the Item Mapping tab. The new item contains the same merge fields as its original.
1.3.2.6 Deleting Customized Source Items
Current table items cannot be deleted from Syndicator.
Note
Deleting a mapped item automatically unmaps the destination item the deleted item was mapped to.
1.3.2.6.1 Deleting a Clone or Split Item
Context
To delete a clone or split item:
Procedure
1. On the Item Mapping tab, right-click on the clone or split item you want to delete.
2. Choose Delete Source Item.
Syndicator deletes the item from the Source Items grid.
1.3.2.6.2 Deleting a Custom Item
Context
To delete a custom item:
Procedure
● On the Custom Items tab, right-click on the custom item(s) you want to delete and choose Delete Custom Item.
Syndicator deletes the item from the Custom Items pane and from the Source Items grid on the Item Mapping tab.
1.3.2.6.3 Deleting a Merge Item
Context
To delete a merge item:
Procedure
● On the Merge Items tab, right-click on the merge item you want to delete and choose Delete Merge Item.
Syndicator deletes the item from the Merge Items pane and the Source Items grid on the Item Mapping tab.
Note
Deleting a merge item unmaps any destination items that have been mapped to its children.
1.4 Preparing Destination Items
This part of the reference guide describes how to manage the destination items available in a syndication map and customize the values which are syndicated to them.
1.4.1 Destination Items Grid
Destination items are the “buckets” into which Syndicator places source data in the syndication file, and the destination items on a map should represent the schema of the intended destination for the records syndicated from the map.
Using Destination Item properties, you can add field-specific transformations to source values, so that the data in the syndication file matches the expected format of the destination system. For more information, see Customizing Destination Item Values linked below.
The destination items available for mapping appear in the Destination Items grid of the Item Mapping tab.
Destination Items Grid Columns
Column Description
Order* The order in which the item appears on records in the syndi
cation file.
Mapped Whether or not the destination item is mapped to a source
item:
● <empty> – unmapped
● – mapped
Name The name of the destination item.
● Name in italics indicates the item is required.
● [Attribute] after an item name indicates the item is an XML attribute.
Type The data type of the destination item.
● Text [x] x = field width set for this item on the Destination Items tab.
Source The name of the source item the destination item is mapped
to, or the static text that will appear in the item on every syn
dicated record.
* Column appears for flat maps only.
Managing Destination Items on XML Maps
The destination items available on XML maps reflect the XML schema associated with the map. For more information, see XML Schema Enforcement in Syndicator.
Managing Destination Items on Flat Maps
New flat maps do not have any destination items; all destination item management tasks for the map must be performed manually.
Related Information
Customizing Destination Item Values [page 39]
XML Schema Enforcement in Syndicator [page 15]
1.4.1.1 Adding New Destination Items to Flat Maps
Context
To add a new destination item:
Procedure
1. On the Destination Items tab, right-click on the Destination Items list and choose Add Destination Item.
Syndicator adds a new destination item to the Destination Items list. The new item inherits the property values of the Default Destination Item. For more information, see Destination Item Property Inheritance linked below.
2. Enter a name for the new item (optional).
3. Enter new property values for the destination item (optional).
4. Press Shift + Enter to save the destination item.
The destination item now appears in the Destination Items grid of the Item Mapping tab.
Related Information
Destination Item Property Inheritance [page 43]
1.4.1.2 Adding a Copy of an Existing Destination Item
Context
To add a copy of an existing destination item:
Procedure
● On the Destination Items tab, right-click on the destination item you want to duplicate and Choose Duplicate Destination Item.
Syndicator adds a new destination item, named Copyof<ItemName>, to the Destination Items pane as well as the Destination Items grid on the Item Mapping tab.
1.4.1.3 Renaming Destination Items on Flat Maps
Context
To rename a destination item:
Procedure
1. On the Destination Items tab, right-click on the destination item you want to rename and choose Rename Destination Item.
2. Enter a new name for the destination item.
3. Press Shift + Enter to save the name change.
The item is automatically renamed on the Destination Items grid of the Item Mapping tab.
1.4.1.4 Deleting Destination Items from Flat Maps
Context
To delete a destination item:
Procedure
● On the Destination Items tab, right-click on the destination item you want to delete and Choose Delete Destination Item.
Syndicator deletes the destination item from the Destination Items pane and the Destination Items grid on the Item Mapping tab.
Note
Deleting a mapped destination item unmaps its source item counterpart. To retain the source data in the syndication file you must map the source item to another destination item.
1.4.1.5 Changing the Destination Item Order on Flat Maps
Context
The order in which destination items appear in the Destination Items tab determines the order in which they appear in the Destination Items grid on the Item Mapping tab.
To change the order in which destination items appear:
Procedure
● On the Destination Items tab, click on a destination item and drag it up or down the list to its new position.
The Item Mapping tab is automatically updated with the new item order.
1.4.2 Customizing Destination Item Values
The Destination Items tab displays the destination item properties for all destination items on the map. These properties control how source values will appear in a destination item when syndicated.
You can customize each destination item individually, or use the default destination item to propagate property changes to all destination items which inherit from it. For more information, see Destination Item Property Inheritance linked below.
As you experiment with destination item properties, switch to the Syndication Preview tab to see the effects they have on the values of their mapped source items.
Related Information
Destination Item Property Inheritance [page 43]
1.4.2.1 Destination Item Properties
Grid Columns for Destination Item Properties
Column Description
Name The name of the property
Inherit/Reset Whether the property gets its value from its parent item:
● – property inherits its value
● – property does not inherit its value
● – property cannot inherit its value
● When the Default Destination Item is selected, the col
umn name changes from Inherit to Reset
● For more information, see Destination Item Property In
heritance linked below.
Value The current value of the map property
● Values in gray are inherited
● Values with a light-blue background have been modified but not yet saved
● Values entered as text must be 255 characters or less
Description of Destination Item Properties
Property Name Description
Name The name of the destination item.
Property Name Description
Required Is the item required on all syndicated records?
● Read-only on XML maps, as value is based on the item’s minOccurs value in the XML schema of the map.
Repeatable XML Node Can the item store repeating source data values?
● For XML maps only.
● Read-only, as value is based on the item’s maxOccurs value in the XML schema of the map.
Static Text Text entered here becomes the value of the selected item on
all syndicated records.
● Applies only to required items that are unmapped.
● Mapping an item replaces static text with source values.
Default Text Text entered here replaces any NULL values found in the
mapped source item’s values.
Hierarchy Style How much of a source hierarchy value to include in the desti
nation item:
● Node Name Only
● Unique Node Name
● Full Pathname
● Partial Pathname from Root
● Partial Pathname from Leaf
● For more information, see Customizing Hierarchy Values in a Destination Item linked below.
Path Delimiter The character used in the destination item to separate de
limited values in a hierarchy value.
Prepend Field Name as Root of Pathname Add the source item name as the root of the source hierar
chy pathname?
● Hierarchy Style = value other than Node Name Only.
● For more information, see Customizing Hierarchy Values in a Destination Item linked below.
Number of Levels in Pathname from Root How many levels (delimited values) in a source hierarchy pathname value to include in the destination item, starting from the root.
● If the Prepend Field Name as Root of Path Names value is checked, the field name counts as a level.
● Hierarchy Style = Partial Pathname from Root.
● For more information, see Customizing Hierarchy Values in a Destination Item linked below.
Property Name Description
Number of Levels in Pathname from Leaf How many levels (delimited values) in the source hierarchy pathname value to include in the destination item, starting from the leaf.
● If the Prepend Field Name as Root of Path Names value is checked, the field name counts as a level.
● Hierarchy Style = Partial Pathname from Leaf.
● For more information, see Customizing Hierarchy Values in a Destination Item linked below.
Multi-Valued Item Delimiter The character used in the destination item to separate val
ues in a multi-valued item.
● For more information, see Mapping Lookup Table Data linked below.
Text Qualifier The character used as the text qualifier.
Max Item Length The maximum text length allowed for the item.
● Disabled on flat maps with fixed-width item format.
Fixed Column Width The specific width of the destination item.
● Enabled only on flat maps with fixed-width item format.
Normalization Type of normalization to apply to text values in this destina
tion item:
● None
● Standard
○ Standard normalization returns a capitalized alpha
numeric string from which all spaces and punctua
tion are removed.
● Standard with Custom Normalization
● Custom Normalization Only
Custom Characters The character string removed from source text when the
Normalization property value is Standard With Custom Normalization or Custom Normalization Only.
● This property is case-sensitive.
Change Case Changes the case of the source text values:
● None
● lower case
● UPPER CASE
● Sentence case
● tOGGLE cASE
Strip HTML Removes HTML tags from source text values.
Character Escaping Type of character escaping to perform on data values in the destination item:
● None: No escaping is performed
● HTML: Escapes all HTML-related symbols
● URL: Applies URL-style character escaping
Property Name Description
Leading Characters to Strip Characters to remove from the start of source data values.
● This property is case-sensitive.
Trailing Characters to Strip Characters to remove from the end of source data values.
● This property is case-sensitive.
Padding Add padding to make all item values equal to the Max. Item
Length or Fixed Column Width property values (whichever is used by the current map):
● None: Do not add padding
● Leading: Add padding before item value
● Trailing: Add padding after item value
Pad Character The character to use as padding in the Padding property.
Whole Number/Fraction Connector The character to use to connect a whole number with a frac
tion in a destination item value (for example, setting this property to "-" results in the source value 3 ½ to appear as 3-½ in the destination item).
Related Information
Destination Item Property Inheritance [page 43]
Customizing Hierarchy Values in a Destination Item [page 67]
Mapping Lookup Table Data [page 52]
1.4.2.2 Order In Which Formatting Properties Are Applied
The order in which formatting-related destination item properties are applied can affect the resulting data values. Syndicator applies formatting properties to destination item values in the following order:
1. Strip HTML
2. Leading Characters to Strip 3. Trailing Characters to Strip 4. Change Case
5. Normalization and Custom Characters 6. Character Escaping
7. Fixed Column Width or Max Item Length 8. Text Qualifier
9. Padding and Pad Character
1.4.2.3 Viewing Properties of Multiple Destination Items
When multiple destination items are selected in the Destination Items pane, Syndicator places into the Value column of each property all distinct values for the property among the selected items. When the same property value is shared by every selected destination item, this single value is displayed in black. When more than one value is present for a property among the selected destination items, each distinct value is displayed in red and separated by a semi-colon.
In the case of a checkbox, Syndicator displays a grayed-out checkbox ( ) to signify the box is checked for some selected items and unchecked for others.
Whatever values you subsequently enter in the Property grid are applied to all selected destination items.
1.4.3 Destination Item Property Inheritance
The inheritance feature of MDM makes it easy to configure multiple destination items at once.
The Default Destination Item
The Default Destination Item on the Destination Items tab is the key to inheritance, a feature through which destination items can be quickly maintained and updated. The importance of the Default Destination Item is that its property values are automatically assigned to all destination items which inherit from it.
1.4.3.1 How Inheritance Works on Flat Maps
All destination items on flat maps inherit from the Default Destination Item, which in turn inherits its values from “factory default” settings. This inheritance hierarchy is illustrated in the following figure:
The following figure illustrates inheritance in action. The Inherit checkbox, when checked, instructs Syndicator to populate a property value from the next level up on the hierarchy, a process which can lead all the way up to the factory default setting. In this example, all destination items inherit their values from the Default
Destination Item, which gets its value from the factory default setting (inherited values appear in gray).
MDM gives you the ability to customize property values at any level of the inheritance hierarchy, except for the factory default setting, by “breaking” inheritance.
By breaking inheritance on the Default Destination Item, you can replace factory default settings with your own custom values and have all of the destination items on your map receive these value changes automatically.
This effect is illustrated in the following figure:
Of course, you may want to customize a property value on an individual destination item or protect a property from inheriting any future value changes. In these situations, simply break inheritance for the individual property on the individual destination item, as illustrated in the following figure:
As this example shows, Destination Item 2 inherits the value change from the Default Destination Item but Destination Item 1, which breaks inheritance, possesses the custom value 10.
1.4.3.2 How Inheritance Works on XML Maps
The premise of inheritance is the same on XML maps as it is on flat maps. Consider the inheritance hierarchy shown in the following figure:
The immediately noticeable difference between the inheritance hierarchy in figure Destination Item Inheritance Hierarchy on XML Maps and the hierarchy shown for flat maps in figure Breaking Property Inheritance on a Destination Item is that destination items on XML maps are nested in a series of internal nodes. The only practical difference this makes in terms of inheritance is that there are increased numbers of levels which must be traversed to get from a destination item (represented in the figure by a leaf node) to the factory default value. At each of these levels, inheritance of a property value can be maintained or broken according to the setting of the Inherit checkbox on that level, as illustrated in the following figure (inherited values appear in gray):
As this example shows, destination items on XML maps do not inherit values directly from the Default Destination Item, as they do on flat maps. Instead, they inherit values from their parent nodes. Leaf Node D inherits the value 50 from its parent, Internal Node 2, which inherits the value from its parent, Record Node.
Record Node inherits from Root Node, which alone inherits from the Default Destination Item.
Contrast Leaf Node D with Leaf Node A, which also inherits its value from its parent. However, because Internal Node 2 breaks inheritance, it does not pass the value of its parent, Record Node, to its children. Instead it passes the custom value 10.
Finally, consider Leaf Node C. It breaks inheritance and so does not inherit from its parent node but instead possesses the custom value 2.
1.4.3.3 Breaking, Restoring, and Propagating Inheritance
As shown in the following figure, the Inherit column on the Properties grid of the Destination Item tab determines whether or not the selected destination item inherits a property value from its parent or breaks inheritance.
When the Inherit checkbox is checked for a particular property, that property inherits its value from its parent.
When the Inherit checkbox is not checked, that property breaks inheritance – its value is no longer inherited from its parent.
There are two ways to restore breaks in inheritance:
● Manually: Select each child item and check the Inherit checkbox for the relevant property.
● Automatically: Propagate inheritance from the parent item. This is a one-step operation that restores breaks in inheritance for the selected property on all child items of the selected destination item.
The Propagate Inheritance command forces all child items of a parent destination item to inherit a selected property value. When the Propagate Inheritance command is performed, Syndicator
automatically checks the Inherit checkbox for the propagated property on all children of the propagating item.
This results in all children of the propagating item inheriting the propagated property value – a convenient tool that saves you from having to manually restore inheritance on each child item.
The following figures show the state of inheritance for a property before and after the Propagate
Inheritance command is performed on the Default Destination Item. (Although an XML map is shown in this example, the command works on flat maps in the same manner.)
Destination Item Inheritance Hierarchy Before Propagation
Destination Item Inheritance Hierarchy After Propagation
1.4.3.3.1 Breaking Inheritance of Property Values
Context
To break inheritance of property values:
Procedure
1. On the Destination Items tab, select the destination item or items containing the property which you want to break inheritance.
2. On the Properties grid, select the property or properties for which you want to break inheritance.
3. Right-click on a selected property and choose Break Inheritance.
Syndicator unchecks the Inherit checkbox on all selected properties, signifying inheritance is broken on these properties.
4. Press Shift + Enter to save the change.
1.4.3.3.2 Restoring Inheritance of Property Values
Context
To manually restore inheritance of property values:
Procedure
1. On the Destination Items tab, select the destination items that contain the inheritance break you want to restore.
2. On the Properties grid, select the property or properties for which you want to restore inheritance.
3. Right-click on a selected property and choose Inherit/Reset.
Syndicator checks the Inherit checkbox on all selected properties, signifying inheritance is restored on these properties.
Note
On the [Default Destination Item], the Inherit column is named Reset.
4. Press Shift + Enter to save the change.
1.4.3.3.3 Propagating Inheritance of Property Values
Context
To propagate inheritance of property values:
Procedure
1. On the Destination Items tab, select the parent item from which you want to propagate property values.
2. On the Properties grid, select the property or properties whose value you want to propagate.
3. Right-click on a selected property and choose Propagate Inheritance. Syndicator opens a confirmation dialog.
4. Click OK on the confirmation dialog.
Syndicator checks the Inherit checkbox of the selected properties on all children of the selected
destination item. To signify which values have been propagated, the Value field of propagated properties is shaded gray on all affected destination items.
Note
Propagating inheritance from the Default Destination Item causes all destination items on a map to inherit the value of the propagated property.
1.5 Mapping Items
This section describes how to map source and destination items on the Item Mapping tab.
1.5.1 Mapping and Unmapping Items
Item mapping is performed on the Item Mapping tab. In general, any source item can be mapped to any destination item with a matching icon.
Icon Source Item Description Destination Item Description
Sends text values Can receive only text values
Icon Source Item Description Destination Item Description Is a repeating MDM structure Is a repeatable XML element Does not send values Cannot receive values
Sends remote key values n/a
n/a Is a mixed XML element which can re
ceive either repeating MDM structures or text
Note
Items with a purple node icon ( ) can never be mapped.
Note
Items with key icons ( ) map to items with text icons ( ).
1.5.1.1 Mapping Source Items to Destination Items
Context
To map a source item to a destination item:
Procedure
1. On the Item Mapping tab, click on an unmapped source item on the Source Items grid.
2. On the Destination Items grid, click on a corresponding unmapped destination item sharing the same icon.
3. Click the Map button.
Syndicator places a mapped ( ) icon in each item’s Mapped column and adds the name of the item’s mapped counterpart to the item’s respective Source or Destination column.
4. Open the Destination Preview tab to verify the output of the mapping.
Note
For more information about the Destination Preview tab, see Previewing the Syndication File linked below.
Related Information
Previewing the Syndication File [page 82]
1.5.1.2 Unmapping Sources or Destination Item
Context
To unmap a source or destination item:
Procedure
1. On the Item Mapping tab, click on a mapped item from the Source Items or Destination Items grids.
2. Click the Unmap button.
Syndicator unmaps the selected item and its mapped counterpart. The mapped ( ) icon is removed from the Mapped column on both items.
Note
Unmapping an item removes the mapped item data from the syndication file. This is reflected in the Destination Preview tab.
1.5.2 Mapping and Unmapping Items on Flat Maps
Destination items on flat maps can be mapped only to source items with text icons ( ).
However, because flat maps are, by definition, non-hierarchical, you are free to map any source item with a text ( ) icon to any destination item on your map, regardless of whether the source item is part of a parent-child structure. For example, you can map qualifiers and deeply-nested tuple fields directly to destination items without having to map their parent items. You can also unmap items on flat maps without restriction.
Icon Item
Category [All Attributes]
● Where Category is the name of the taxonomy field of the repository.
