Specializing in Support and Service Software

I want to introduce a handy library called Dovetail DataMap created during the development of Dovetail Mobile. DataMap 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 to receive data and a map which defines how data in your Clarify database should populate that .Net 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 Data Map

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

public class SolutionMap : DovetailMap<Solution>
{
	protected override void MapDefinition()
	{
		FromTable("probdesc")
			.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 ookie 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(FilterType.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.

DataMaps 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 DataMaps 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);
}

DataMaps 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 DataMap 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.