A MatchSearch in the Import configuration is used to Match assets. It is used in two scenarios:

1. Setting metadata on existing assets

2. Replacing existing assets with new versions

In either case, the Importer needs to know what assets to work with, and this is exactly what the MatchSearch is used for. 

The standard search, delivered with the Importer app, goes by the name DamImporterMatchSearch and it is used as the default way to perform matching logic. It is entirely up to the Importer user whether to use this search or their own, as long as it conforms to a couple of rules, as described here.

Rules for the MatchSearch

1. There must be a searchfield defined with the ID sFilename. The ID is case-sensitive. This is the input field the Importer will use.

2. The sFilename searchfield must have the valueHandler InList. The Importer searches for 50 search tokens at a time, so this is the only valueHandler that will work.

3. There must be a valuefield defined with the ID filename, and it must reference the same metafield or table/column as sFilename.

4. The valuefield "assetId" must be present and refer to "asset.assetid" and the Id must be "assetId". It is case-sensitive, so if this is changed to ie. "assetid" nothing will ever be matched.

While not a rule for the search definition, it is also important to note that the DAM's read access is still respected, so the user configured for the Importer must have read access to the assets needed.
Any search definition can be used as long as these rules are followed.

About the default DamImporterMatchSearch

The match search delivered with the Importer uses the asset's title metafield to match. This does not meet all customers' requirements, so for some, it is necessary to either change the existing one or create a new search definition.

How to define a new search for use with the Importer

First, navigate to the ConfigManager and the DAM node:

Open

Depending on the version it was born with, it might look slightly different on your DAM.

Navigate to the Searches tab and click the Add new search button:

Open

Give the search a name (for this example, it is DamImporterMatchSearchByAssetId):

Now click the Use another search as template button, wait for it to load, and navigate to DAM Center 4.0.0:

Click done.

Now the other searches dropdown is available, find and select DamImporterMatchSearch, then select Asset as item type:

Click Create a new search.

Now, the editing view for the new search will be automatically selected for you. Mark the sFilename field while on the input tab and then click Delete selected item:

Now click add, and select assetid on the table-column tab. Here Comparison type (it's what in other contexts is called valuehandler) must be InList, and the ID must be sFilename:

The input type is unused and irrelevant here, but unfortunately, we're forced to choose one. Either will work for the purpose of the Importer. Click Create.

Now, go to the output tab and repeat the process. Start by deleting the field with the ID filename:

You may notice that assetid is already a valuefield. This is needed, and we need it for the purpose of matching as well, so continue by clicking add, which will open the UI to select a field. Select 'assetid', and here, the ID must be filename.

Click Create.

Now, only two steps are left, and the first is to save the search, so do that.

The last step is configuring the Importer configuration to use this search, which is done by entering the name of the search into the MatchSearchName config tag.