Modern Software Experience

2011-08-10

OhanaService

Family Tree Maker 2012 Public Beta

It is Discover your Ancestry.com month. It started with the Family Tree Maker 2012 Public Beta, announced on the FTM-TECH mailing list. Oddly, it turned out that we had to download FTM_2012_Public_Beta.zip from Dropbox. As Ancestry.com had announced already, the big new feature in Family Tree Maker 2012 is TreeSync, the ability to sync your desktop Family Tree Maker database with online Ancestry.com Member Trees.

Another link led to the FTM Sync Beta message board, where Duff Wilson, the product manager for Family Tree Maker, posted a link to FTM_2012_Public_Beta2.zip and a list of TreeSync limitations.

OhanaService

The new TreeSync feature invites comparison to AncestorSync, a product of Real-Time Collaboration. Real-Time Collaboration is the company that, back in February, acquired Ohana Software, makers of FamilyInsight.
Ancestry.com publishes obfuscated download links, but it is easy to see the actual download location when you are downloading, and the download location for Family Tree Maker 2012 Public Beta 2 is a subdirectory of service.familytreemaker.com/ohanaservice.

The OhanaService name has nothing to do with Ohana Software, Real-Time Collaboration or AncestorSync.

code name

A bit of googling makes it clear that Ancestry.com has been using the subdirectory OhanaService for some years. The OhanaService name has nothing to do with Ohana Software, Real-Time Collaboration or AncestorSync. Ohana seems to have been the code name for New Family Tree Maker, a code name that made it into the final product and some directory names.
That explains why you download Family Tree Maker 2012 Public Beta 2 from a subdirectory of service.familytreemaker.com/ohanaservice.

Family Tree Maker FAQ Answer ID 30732

When you google for service.familytreemaker.com/ohanaservice, you'll find several links, all of them related to the New Family Tree Maker product.
The link https://service.familytreemaker.com/ohanaservice/authenticate.ashx is mentioned in the Family Tree Maker FAQ entry 3072, Troubleshooting Family Tree Maker 2008, 2009, 2010 or 2011 Registration.
The link https://service.familytreemaker.com/ohanaservice/Plan/Dashboard.aspx looks like the Dashboard shown within the Family Tree Maker Plan tab and http://service.familytreemaker.com/OhanaService/places/LiveMapV2.aspx looks likes Family Tree Maker's map window.

Family Tree Maker OhanaService

SearchService

The most interesting OhanaService URL I found through Google is https://service.familytreemaker.com/ohanaservice/SearchService.asmx, the Family Tree Maker SearchService.

Family Tree Maker SearchService

Note the SearchService banner and the helpful text below it: The following operations are supported. For a formal definition, please review the Service Description..
When you click the Search Description link, you are shown the WSDL definition for the SearchService:

Family Tree Maker SearchService WSDL

Family Tree Maker web service

The SearchService is a web service that familytreemaker.com offers. That service is used by - what else? - New Family Tree Maker. The SearchService must be what New Family Tree Maker uses to offer web search inside the application.

The SearchService page is the home page of that web service, and it is a very helpful page. The page itself summarises the service by listing the names of the available functions. That overview of its function names give you some idea of what this web service is about already, but this page is much more helpful. You can click on each function one to find a page with example code that shows you exactly how to use this web service and that WSDL page is nothing less than the official definition of the entire web service. WSDL is so official that you can use it to generate the code you need to use the service.

New Family Tree Maker is a .NET application. Most .NET applications are created using Microsoft Visual Studio, and helpful web service pages like this are generated by - you guessed it - Microsoft Visual Studio.

SearchService functions

Family Tree Maker SearchService
FetchRecord( providerId, moniker )
GetHint( providerId, criteria )
GetHintFiltered( providerId, criteria )
GetProviders()
GetRecordStatus( providerId, moniker, context )
GetRecordsByStatus( providerId, context, status )
GetTemplate( providerId, criteria )
SetRecordStatus( providerId, moniker, context, status )

The WSDL definition of the familytreemaker.com SearchService tells you exactly what parameters each function takes, and what kind of results it returns, The names of the functions and their parameters are helpful, but it remains a formal description meant for automated tools.
The web search functionality of New Family Tree Maker, the application the SearchService was created for, shows how the web service is used in practice.
What's missing in between is a human-oriented description of the Family Tree Maker SearchService; some conceptual documentation that helps programmers understand what this web service does and does not offer, how its various functions work together, and what each parameter is for.

SearchService providers

When you make a quick overview showing just the parameters each function takes, you'll notice that most functions expect a providerId. The only function that does not expect a providerId is GetProviders; the GetProviders function returns a list of providers you can use with the other functions.

Family Tree Maker SearchService GetProviders result

providerIdNameLabelType
1AncestryAncestry.comMyFamily
2RootsWebRootsWeb.comMyFamily
3GenealogyGenealogy.comMyFamily
101GoogleGoogle.comOther
102YahooYahoo.comOther
103LiveBing.comOther

The GetProviders function is the simplest function of all; it is the only function that does not expect any parameter. Moreover, its example page shows that you do not even need to use SOAP to call this function, you can use HTTP instead. In plain English: you only need to type a URL.

You can call upon the Family Tree Maker SearchService GetProviders function by typing http://service.familytreemaker.com/ohanaservice/SearchService.asmx/GetProviders in the address bar of your browser. When you browse to that URL, the result is an array of search providers.
The screenshot shows the XML result returned by this function, repeated in the table for readability. This GetProviders result tells what value the other functions expect the providerId to be, and what each of these possible values means. So it seems that using the SearchService API normally starts with calling GetProviders to find out what search providers are supported, and then picking one of these to use with the other functions.

The easiest way to use this web service is to start New Family Tree Maker.

status

I have no idea what the legal status of this web service is. You'll have to ask a lawyer.
I only know that it is publicly available on the web; no password, registration key or encryption required. The familytreemaker.com SearchService is publicly available, complete with helpful home page, example code for each function and official WSDL definition. Ancestry.com provides all you need to get started using this web service, but that does not mean it makes sense to do so.
The familytreemaker.com SearchService was created in support of New Family Tree Maker and the easiest way to use this web service is to start New Family Tree Maker.

links

Family Tree Maker 2012

Ancestry.com Search Service API

web standards