GEBestBetAdder – SharePoint tool to Export and Import Best Bet Keywords

GEBESTBETADDER is a FREE command line application that carries out the following:

1: Lists existing keywords and best bets

2: Connects to a managed SharePoint keyword list for the import into a keyword search list

3: Exports keywords

4: Imports keywords

5: Clears keywords

The best things about this app? It’s now FREE! Plus, it works with any search host on any SharePoint site; it imports keywords and even multiple BestBets associated with those keywords, it exports to an XML file that can be manipulated.

Important. This tool is console based must run on a server in the SharePoint on-premise farm, will work in SharePoint 2007 / 2010 for export, 2010 for import.

A Best Bets import from SharePoint 2010 to SharePoint 2013 GUI is currently being developed. The GUI version will work across SharePoint 2010 and SharePoint 2013 on-premise, allowing you to migrate keywords and best bets in 2010 to SharePoint 2013. The GUI tool will also allow you to directly manage 2013 best bets (known as Promoted Results) and Query Rules. The GUI tool will be available by end of June 2014. Further work is being planned to ensure this tool works from SharePoint 2013 on-premise to 2013 SharePoint online. If you are interested in that tool please contact us.

Now back to GEBestBetAdder for SharePoint 2007 and SharePoint 2010. One final point before reading on. This tool has taken quite a while to create, and many thanks to all those who helped me create it. However, just because the tool is free that does not mean that support for the tool is also free – best endeavours is available though.

1 Switches

Switch	Description
-w	Search host (e.g.  http://mySharePointsite/search
-k	Url of the managed list (e.g.  http://mykeywordlistsite)
-l	Name of the list that holds your own  keywords (relates to -k switch)
-x	Shows the names of the fields in the above   list (relates to -k and -l)
-e	Exports the keywords and best bets
-c	Configuration file that maps what fields in  the managed list maps to fields in the  search host
-s	Ignores the check of the synonym length or existence. Use this switch if you wish to import all keywords whether they have associated synonyms or not. Note that if this switch is used, that synonyms for the associated keyword will NOT be imported if the synonym entry exceeds 100 characters
-u	Import XML into search host
-z	Deletes all keywords from a Search Host

2. How to Use

Note. GEBESTBETADDER is a server based application. You must install it on one of the servers in your SharePoint farm.

Best method is to simply create a folder on your SharePoint farm, and extract the application into that folder.

Read the following sections on how to export, import, write from a list and delete  keywords. Also check out the switches  section to find out more about the applications settings.

2.1 Exporting

Using the -e switch will export to a file called SearchKeywords.XML in the same directory.

You must ensure the that the -w switch is used, obviously because you need to specify the search host where the existing keywords are stored.

For example, if the keywords was stored here:

http://search

then the command would be:

GEBESTBETADDER -w http://search -e

That would then export all keywords and bestbets within http://search to a file in the same directory called SearchKeywords.XML

Note.

It is a good example to have a test search host with a number of test keywords and best bets. This way you can export that and use the searchkeywords.xml in your favorite xml editor to modify it and update the keywords via import.

2.2 Importing

Importing keywords is simply the same as exporting in terms of the command except that you use the -u switch. This takes the XML file used as part of the -u switch and imports it into the search host specified using the -w switch.

So for example, if the search host that you want to import into is http://search and the filename xml you wanted to import into it was called Keywords.XML then the command would be as follows:

GEBESTBETADDER -w http://search -u KEYWORDS.XML

This would then take the keywords.xml, format and check and import into http://search

Notes.

• It is crucial that the fields used in the keywords.xml are the same ones used in the search host. To get around this it is best to export from a test host then add your keywords and best bets using your favorite XML editor, then rename the xml file to say Keywords.XML
• If your keyword, related Syonym, Best Bet, URL is empty the keyword will not be saved. There must be at least one best bet per keyword
• If the keyword, Best Bet Title or Description exceeds 100 characters it will not be saved.
• If the start date of the keyword is before the date of the import it will not be saved
• The contact will be saved whether its valid or not
• If the keyword already exists then the related keyword will be deleted and overwritten with the updated keyword information
• Use the -s switch if you wish to import all keywords whether they have associated synonyms or not. Note that if the Synonym entry does exist, but exceeds 100 characters no Synonym will be set for the associated keyword.

2.3 Writing from an existing sharepoint list

Instead of using a XML files for the import into a search list, you can use an existing list from SharePoint. This list should have the fields used to store the following:

• Keyword
• Synonyms
• Best Bet Title
• Best Bet URL
• Best Bet Description
• Keyword Definition
• Keyword Contact
• Keyword Status

 

Note the Keyword Status – that could be an identifier recording whether the keyword has been injected into the list. This means you can control from the list what should and should not be imported. This field could be a choice field holding the terms

• IMPORTED
• NOT DONE

Then you could set the keyword status of the ones you wanted imported to the term NOT DONE.

A template list is included with the application which you could import into the list templates then create a custom list from the template.

Important.

In order to use this feature three switches are required:

-c

This is the Configuration File that lists the fields of the list above. The fields in this must be in order and exist in the related list. See  Configuration File for further information

-l

This is the name of the SharePoint List (as displayed in View All Site Content on the site)

-k

This is the URL of the site where the list is located. Note that the SharePoint list must be at the root of the site hierachy.

 

Example.

The search host is http://search, the SharePoint list is on the url http://mySharePointsite, the name of the list is Search Keywords and the configuration file holding the files to be used in that list is SearchKeywords.cnf:

GEBESTBETADDER -w http://search -k http://mySharePointsite -l “Search Tems” -c SearchKeywords.cnf

2.3.1 Configuration File

The configuration file is used only when  importing from a SharePoint custom list.

This file is simply a text file listing the fields in  the search list you store your keywords in.

To find out the fields in the relevant SharePoint list use this  command:

GEBESTBETADDER -k http://mySharePointsite -l  “Search  Terms” -x

where http://mySharePointsite is the site that holds the list called Search Terms.

The fields in the list are in the order of creation, not in alphabetical order. Note some of the names of these fields have XX20 in them – that’s a space.

Now, all you have to do is create a configuration file that lists those fields and in the following order:

KEYWORD TERM

SYNONYM

BEST BET TITLE

BEST BET URL

BEST BET DESCRIPTION

KEYWORD DEFINITION

CONTACT

EXISTINGBESTBETS

STATUSFIELD

IDENT FIELD

 

What do each of these mean?

KEYWORD TERM.

This is the keyword.

SYNONYM

This is the synonyms separated by SEMI COLONS

BEST BET TITLE

Easy, its the associated BEST BET TITLE

BEST BET DESCRIPTION

Easy, its the associated BEST BET DESCRIPTION

KEYWORD DEFINITION

Some editorial text associated with the keyword

CONTACT

The user id who manages the keyword

EXISTINGBESTBETS

This is a list of other keywords within the list associated with this one

Note. ExistingBestBets can be empty; if not they MUST be separated by SEMICOLONS and must already exist in the list.

Ok, here’s the interesting part:

STATUSFIELD is very important. This is the field in the list that stores the choices in the list defining whether the item in the list is going to be added or updated in the keyword host.

IDENT CODE is the choice item in the above STATUSFIELD that denotes when a keyword should be added.

For example, if STATUSFIELD had the following choices:

INCLUDE IN SEARCH

NOT INCLUDE

then you would set the IDENT CODE to be INCLUDE IN SEARCH if you wanted any item whose STATUSFIELD = INCLUDE IN SEARCH

2.3.2 Construct Configuration File

Using the -x switch to list out the fields from the list, create a text file called say  SearchTerms.CNF and enter on each line and in order as given above the fields to use.

Do NOT forget the Statusfield or the IDENT code entries as described above or the  routine will fail.

If you do not want to use certain fields in the configuration file, that’s ok, just leave a  blank. However, the following lines must be filled and with the exception of the IDENT  FIELD CODE must exist in the SharePoint list:

KEYWORD TERM

SYNONYM

BEST BET TITLE

BEST BET URL

BEST BET DESCRIPTION

STATUSFIELD

IDENT FIELD CODE

2.3.3 Test Configuration File

Its always best to have a test site running so you can target that using the  configuration file you have constructed. Never test this against a live environment. This  is just so you can ensure that the configuration file is correct, that the output is correct  and that the number of entries in the search system is what you expected.

2.4 Deleting keywords

To delete keywords, specify the search host and use the -z switch.

For example, to remove all keywords from a site called http://mySharePointsite enter this:

GEBESTBETADDER -w http://mySharePointsite -z

Handle with care! This should ONLY be carried out when you are absolutely certain you want to remove the keywords and cannot be reversed

Summary

GEBestBetsAdder allows you to manage SharePoint keywords; just the tool needed when having to migrate to a new farm or rebuild site collections that will require keywords being re-injected.

There is a GUI version which has mountains of more features, and that will be on sale shortly on this site. If you have any further queries concerning this tool or the GUI version please contact me.