Using the Form onLoad Event to Default Task Values
Summary: This code example will highlight some of the customization features in Microsoft CRM 4.0 including:
- Activity customization
- Client-side programming model (form and field events)
When creating a new task, we know that customers frequently want to make the following changes to the default form:
- Change the default duration from 30 minutes to blank.
- Auto-populate today’s date into the Due Date field.
These two changes might seem simple at first, but digging deeper into the details of these two fields reveals some obstacles to make these changes. Because the Duration field looks like a picklist field, you would expect to be able to just change the default value by editing the Duration attribute of the Task entity. However, even though the Duration field appears to be a picklist, it is actually a special field used on various activities in Microsoft CRM. For these special fields, you can not set a default value (or add picklist values) like you can for normal picklist fields.
In addition to the Duration field nuance, DateTime attribute data types do not have a default value. Since the Due Date field uses the DateTime data type, we can’t use the attribute editor to specify today’s date as the default value in the Due Date field. Hence, we now have two issues to solve regarding the customer requests.
Despite the two problems we just outlined, we can easily meet the customer’s request to change the default task form by leveraging the form OnLoad event of the task entity’s form.
To accomplish this we will add a simple script to the form OnLoad event and Microsoft CRM will run our script everytime a user opens the task form. When it runs, our script will programmatically change the value of the Duration and Due Date fields to the values we specify.
The only other issue we need to address with our script is to make sure that we only change the Duration and Due Date values when users create a new task. Obviously, we wouldn’t want to change the Due Date and Duration values when users open previously created tasks. When we’re done, every time a user creates a new task, our scripts will set the Duration to blank and then default today’s date as the due date. The flow chart for this customization looks like the following:
Now we’ll walk through how you would actually setup, test and deploy this code.
Procedure: Using the Form OnLoad Event to Default Task Duration and Due Date
1.
Navigate to Settings -> Customization -> Customize Entities. Double click the Task entity. The entity editor will appear.2.
Click Forms and Views. Double click Form. The form editor for the task entity will appear.
3.
Click Form Properties and the editor window will appear. From here, you see that you can choose to add a script to the form
OnLoad or OnSave event.
As we previously discussed, we want to use the OnLoad event so that the script runs when users open a form.4.
Select OnLoad and click Edit. The Event Detail Properties window will appear. In this window, enter the following code:var CRM_FORM_TYPE_CREATE = 1;
var CRM_FORM_TYPE_UPDATE = 2;
switch (crmForm.FormType)
{
case CRM_FORM_TYPE_CREATE:
crmForm.all.actualdurationminutes.DataValue = null;
crmForm.all.scheduledend.DataValue = new Date();
break;
case CRM_FORM_TYPE_UPDATE:
// do nothing
break;
}
A quick review of this code shows that Microsoft CRM allows us to programmatically set the values on the form using
javascript. This code sets the actualdurationminutes field (the schema name for Duration) to NULL, which means the same
as blank. It also sets the scheduledend field (the schema name for Due Date) to today’s date using the javascript Date( )
function. The OnLoad event will run this script everytime a user opens a form, but remember we only want to set the default
values when users create a new task. Therefore, we added the cases so that our script only runs for the form type of 1.
Microsoft CRM assigns a form type value to each form (1-Create, 2-Update, 3-Read Only, etc.) so that you can tie this
information into your scripts just like we needed in this example. In this script, if the form type is 2 that indicates
it is an update form so we don’t alter the Due Date and Duration field values.5.
After you enter the code, click the Event is enabled checkbox. This box indicates whether or not Microsoft CRM should run
your script when it fires the OnLoad event. The screen should look like this:
6.
Next we’ll setup the Dependencies related to our code to make sure that no one accidentally removes the Duration or
Due Date field from the task form (because our script would generate an error if those fields were missing).
Click the Dependencies tab.7.
You’ll see two columns: Available Fields and Dependent Fields. The Available Fields column lists all of the fields that appear
on the task form. To make Due Date and Duration Dependent Fields, select those values in the left column and then click
the ">>" button. Microsoft CRM will move those fields into the Dependent Fields column.
Click OK.8.
Click Ok. You should be back on the task form editor now.9.
Next we want to use the form preview feature to test the code we just added. Before you try preview, make sure you save the
changes you made by clicking the Save button.10.
To test the script on the create form, click Preview -> Create Form and you should see the following:
You’ll see that the Duration picklist defaults to a blank value, and the Due Date field displays today’s date and time!11.
If you try testing your script on the update form using Preview -> Update Form, you’ll see that the Due Date field does not
default to today’s date just like we expect (because our script only runs on Create forms). However, you might notice
that the Duration field appears blank. When you use the Update Form preview Microsoft CRM shows you an update of a blank
record so it will always show picklists as blank, just like it does for the Priority picklist on the task form. So the
script ran correctly, but the fact that Microsoft CRM shows an update of a blank record might causes some little nuances
like the blank picklists.12.
Now that you tested the script and it works correctly, you’re ready to publish. To publish the task entity, return to the
entity editor and click Actions -> Publish in the top tool bar.13.
That’s it, you’re done!This example showed how you to tap into the form OnLoad event to manipulate field values before users see the form. Even if you didn’t understand the syntax of this code example, you should understand the concepts of how you can highly customize your forms by adding custom scripts that tie into Microsoft CRM form events.
Of course, this example just shows a very simple tweak to the task form, but you can get very creative with additional custom code and the powerful programming model of Microsoft CRM 4.0.
