I was recently assigned to transfer data from an ACT! to Microsoft CRM 3.0. The data included importing all of the present and historical activities.
In CRM 3.0, all tasks, emails, appointments... are classified as activities. In order to import the data effectively, I needed to understand what each field in the task object of the CRM 3.0 web service represented.
I will explain each field in this article.
To get the most out of this article, you need to understand how the CRM 3.0 web services work.
Take a look at the Microsoft CRM 3.0 documentation on MSDN. It is very detailed and will help you get started.
In this article, I am assuming that you imported the web service.
Using the Code
First of all, what you need to do is create the task object.
task t = new task();
CreatedOn property. When creating any CRM object programmatically, you will need to create a new instance of the non string property types.
CRM provides its own custom objects, in the case of a
DateTime object create a new
CrmDateTime instance and then access the value of the property.
*** Please note that CRM will modify the date to a different standard time zone for storage in the database, this is only done if the data is inserted using the API or the user interface so don't be alarmed if your dates are different.
If your task has a priority, then use the following code:
t.prioritycode = new PickList();
t.prioritycode.Value = Convert.ToInt32("0");
Picklists are handled using the
PickList object. Make sure that you have the corresponding value CRM.
You must do the mapping between your lists and CRM picklists. If the data is not there, add it through the CRM interface and don't forget to publish your changes otherwise the API will throw an exception. Most activity objects require a subject. Please be aware of the length of the subject data. The task subject is limited to 150 characters, it will also truncate at the first line break instance. If you don't do this test, it will be hard to debug because the only error reported by the API is "a general SQL error".
In ACT! there is no subject line, so I needed to import the trailing text into the description property.
t.subject = "my first task";
t.description = "my first task description"
You can of course create tasks in the past, present or the future. This is handled by the following lines of code:
t.scheduledstart = new CrmDateTime();
t.scheduledstart.Value = DateTime.Now.ToString();
Use the "
scheduledend" property to set the end of the activity, this is not required.
t.scheduledend = new CrmDateTime();
t.scheduledend.Value = DateTime.Now.ToString();
The following properties are required and are explained in greater detail.
regardingobjectids are of type
t.regardingobjectid = new Lookup();
t.regardingobjectid.name = "my name";
t.regardingobjectid.type = "type of object";
t.regardingobjectid.Value = new Guid("");
name property is self explanatory; it is the name of the user that created the object. The
type is more complex, you need to provide the name of the entity as it is specified in crm. The
type for a user is "
systemuser". The authors of the API provided us with an
enum class with all the entity names and their type codes.
This would return the
This would return the type code (you don't really need this in most cases).
Value property is of type
GUID; all primary keys are stored as unique identifiers.
RegardingobjectID is very important but not required. This is the property that needs to be set if you want to associate the activity with a client, order... or any entity that is configured to accept activities.
ownerid property is similar to the
Lookup where they share the same fields. Substitute the
Lookup object for the
t.ownerid = new Owner();
t.ownerid.name = "my name";
t.ownerid.type = "type of object";
t.ownerid.Value = new Guid("");
owner is usually of type
User but it can also be a
If you need to set the duration for the task, use the following property. The duration is stored as an integer in minutes.
t.scheduleddurationminutes = new CrmNumber();
t.scheduleddurationminutes.Value = 45;
Actually creating the task on the server is simple. An instance of the
CrmService object is needed.
***This is for .NET 2.0***
CrmService service = new CrmService();
service.Credentials = System.Net.CredentialCache.DefaultCredentials;
When you create a new entity, CRM will return a newly created
If for whatever reason the creation fails, the API will throw a
SoapException and the actual error message will be located in the
Guid newTaskID = new Guid();
newTaskID = service.Create(t);
string strMessage = ex.Detail.InnerText;
If the task is a historical activity, than you need to set it as completed using the
SetStateTaskRequest object to ask CRM to close the activity, each activity type has its own
SetStateTaskRequest tr = new SetStateTaskRequest();
tr.EntityId = newTaskID;
tr.TaskState = new TaskState();tr.TaskState = TaskState.Completed
tr.TaskStatus = -1
It is that simple.
Have a great day!
Oshri Cohen www.nuvoit.com