How To Create a Task in CRM 3.0

Introduction

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.

Background

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(); 

Set the 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.

The regardingobjectids are of type Lookup.

t.regardingobjectid = new Lookup();
t.regardingobjectid.name = "my name";
t.regardingobjectid.type = "type of object";
t.regardingobjectid.Value = new Guid("");

The 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 string "systemuser".

EntityName.systemuser.ToString();

This would return the type code (you don't really need this in most cases).

Convert.ToInt32(EntityName.systemuser).ToString();

The Value property is of type GUID; all primary keys are stored as unique identifiers.

The 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.

The ownerid property is similar to the Lookup where they share the same fields. Substitute the Lookup object for the Owner object.

t.ownerid = new Owner(); 
t.ownerid.name = "my name"; 
t.ownerid.type = "type of object"; 
t.ownerid.Value = new Guid("");

The owner is usually of type User but it can also be a Queue.

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 GUID.

If for whatever reason the creation fails, the API will throw a SoapException and the actual error message will be located in the Detail.InnerText property.

Guid newTaskID = new Guid();

try
{
newTaskID = service.Create(t);
}
catch(System.Web.Services.Protocols.SoapException ex)
{
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 SetState class.

SetStateTaskRequest tr = new SetStateTaskRequest();
tr.EntityId = newTaskID;
tr.TaskState = new TaskState();tr.TaskState = TaskState.Completed //or Canceled,Open;

tr.TaskStatus = -1 //set this to -1 so that CRM can decide the appropriate status.
service.Execute(tr);

It is that simple.

Have a great day!

Oshri Cohen www.nuvoit.com