Introducing Dovetail DataMap

Update: I’ve modified this post as what were called DataMaps are now called ModelMaps. You can download the source from the Dovetail Bootstrap project.

I want to introduce a handy library called ModelMap we created during the development of Dovetail Mobile. ModelMap makes it easy to populate model objects from a Clarify/Dovetail CRM database. It is a sort of one-way Clarify specific object relational mapper tool.

Your CRM data to Objects

It is very common to need a way to pull data out of your CRM for creation of a user interface. What if you could define a plain old C# object as your model and a map which defines how data in your Clarify database should populate that .Net model class? Does this sound better than hand rolling your own code every time? I hope it does. Let’s take a look at a scenario.

A Plain Old C# Object

Let’s say you want to create a user interface that displays solutions. First thing you do is create a class with a public property for each piece of data about the solution you wish to display.

public class Solution
	public string ID { get; set; }
	public DateTime Created { get; set; }
	public string Title { get; set; }
	public string Description { get; set; }
	public bool IsPublic { get; set; }

A ModelMap

Next up you define a map for the Solution object that describes where the data for each Solution property comes from.

public class SolutionMap : ModelMap<Solution>
	protected override void MapDefinition()
			.Assign(d => d.ID).FromIdentifyingField("id_number")
			.Assign(d => d.Title).FromField("title")
			.Assign(d => d.Description).FromField("description")
			.Assign(d => d.Created).FromField("creation_time")
			.Assign(d => d.IsPublic).BasedOnField("public_ind").Do(isPublic => isPublic == "1")

In the map above you are seeing what is called a Fluent Interface. The idea is to make this map very readable while being easy to edit and extend. Hopefully after taking a few seconds to look between the Solution class and this map you’ll understand what is happening.

  • What table is the solution map getting its data from? The Solution object maps to the probdesc database table.
  • Which field is the identifying field? The id_number field maps to the ID property and is the identifying field.
  • When is the IsPublic property true? When the public_ind field is “1”.

The map above acts as the glue between the Solution class and another object called an assembler.

Assembling Solutions

The assembler does all the hard repetitive redundant work for you. It does stuff like querying and retrieving data from the database, and with that data, creates Solution objects. The best part is all you have to do is create one and tell it which solutions you want.

Getting a solution by identifier
//Use an assembler to retrieve a solution by id. 
string solutionID = "124";
Solution solution = solutionAssembler.GetOne(solutionID));

Remember the identifying field in the map above? When the assembler is getting one Solution filtering by the id_number field. Here is a view of the Solution object from the debugger.


Solutions created in the last week
Solution[] solutions = solutionAssembler.Get(f=>f.WithinDays("creation_time", 7));

Getting solutions from the assembler in an ad hoc manner requires that you give the assembler criteria about which solutions you want returned. Take a look at the documentation for all the types of filters you can use and at Dovetail SDK advanced filtering if you want to learn how to chain these filters together.

ModelMaps In Production

How would you use something like this? The Solution class we are using here is very similar to what Dovetail Mobile is using.


Our Dovetail Mobile product is using the new ASP.Net Model View Controller (MVC) framework. We use the ModelMaps library to create the Model part of this equation. Here is an example of all the work our Mobile solutions controller needs to create the screen you see above.

public ActionResult Show(string id)
	var solutionViewModel = _solutionAssembler.GetOne(id);

	return View("ShowSolution", solutionViewModel);

ModelMaps makes doing the data retrieval for this controller action quite simple.

Finally – What do you think?

Are you a Dovetail SDK customer? Can you see how Dovetail ModelMap might be handy in your application? Do you want to know more? I’ve just hit the surface with this post. We want to see if there is more interest before dedicating more time and resources to making something like this available. Post a reply or send me a Tweet with what you think.