Set field values using parameters passed to a form
Applies To: Dynamics CRM 2013
The content in this topic can be used for Microsoft Dynamics CRM 2013 and Microsoft Dynamics CRM Online. You can set default values for new records created by users by specifying attribute values in the URL that is used to open the form. By default, these values are set in the form, but can be changed by users before they save the record.
In This Topic
Passing parameters to set field record values
Example: Set the value for string fields
Setting values for lookup fields
Example: Set the value for lookup fields
Example: Set the value for date fields
Example: Set the value for option set fields
Example: Use Xrm.Utility.openEntityForm to open a new window
Example: Use window.open to open a new window
Passing parameters to set field record values
Note
See the technical article Use the Form Query String Parameter Tool to Demonstrate Setting Default Field Values in New Record Forms. This article includes a link to a managed solution you can install and use to generate a URL to set values in the form.
You can pass parameter values to the form to set field values using the Xrm.Utility.openEntityForm function. For an example, see Example: Use Xrm.Utility.openEntityForm to open a new window.
When you open a new form by using the URL address, you can include arguments in the extraqs parameter to set field values. The following requirements must be met:
You must encode the parameters passed in the extraqs parameter. To encode the parameters, use encodeURIComponent.
The names of the query string arguments must match or include the names of attributes for the entity.
The values passed must be valid.
The value can’t be a script.
Any attempt to pass an invalid parameter or value will result in an error.
For Boolean fields, use either an integer value of 0 or 1, or a text value of true or false to set the value.
For DateTime fields, use the text value of the date.
Example: Set the value for string fields
The following sample sets the value for the Name field of a new account record to "New Account".
The unencoded value for the extraqs parameter is “name=New Account”.
/main.aspx?etn=account&extraqs=name%3DNew%20Account&pagetype=entityrecord
Setting values for lookup fields
The following table describes five types of lookup fields. For examples using lookup fields, see Example: Set the value for lookup fields and Example: Use Xrm.Utility.openEntityForm to open a new window.
Lookup Type |
Description |
|---|---|
simple lookup |
Allows for a single reference to one type of entity. |
customer lookup |
Allows for a single reference to either an account or a contact record. |
owner lookup |
Allows for a single reference to either a team or a system user record. |
partylist lookup |
Allows for multiple references to multiple entities. |
regarding lookup |
Allows for a single reference to multiple entities. |
The following guidelines apply when setting the value of a lookup on a form using a query string argument:
For simple lookups you must set the value and the text to display in the lookup. Use the suffix “name” with the name of the attribute to set the value for the text.
Don’t use any other arguments.
For customer and owner lookups you must set the value and the name in the same way you set them for simple lookups. In addition you must use the suffix “type” to specify the type of entity. Allowable values are account, contact, systemuser, and team.
You can’t set the values for partylist or regarding lookups.
Example: Set the value for lookup fields
To set values for lookup fields, use the data value, the name value, and for customer or owner lookups only, specify the type value for the respective field. The following sample sets the owner field to a user named “Mark Folkerts”.
The unencoded value for the extraqs parameter is “ownerid={B8C6E040-656E-DF11-B414-00155DB1891A}&owneridname=Mark Folkerts&owneridtype=systemuser”.
/main.aspx?etn=lead&pagetype=entityrecord&extraqs=ownerid%3D%7bB8C6E040-656E-DF11-B414-00155DB1891A%7d%26owneridname%3DMark%20Folkerts%26owneridtype%3Dsystemuser
Example: Set the value for date fields
The following sample sets the Est. Close Date field for a new opportunity to January 31, 2011. The unencoded value for the extraqs parameter is ‘estimatedclosedate=01/31/11’.
/main.aspx?etn=opportunity&extraqs=estimatedclosedate%3D01%2F31%2F11&pagetype=entityrecord
Example: Set the value for option set fields
To set the value for an Option set field, set the integer value for the option. The following sample sets the Role field value to “Decision Maker” in a new contact record.
The unencoded value for the extraqs parameter is “accountrolecode=1”.
/main.aspx?etn=contact&extraqs=accountrolecode%3D1&pagetype=entityrecord
Example: Use Xrm.Utility.openEntityForm to open a new window
The following sample sets default values on several different fields and shows how to use the Xrm.Utility.openEntityForm function. It is equivalent to the previous example that used the window.open method.
function OpenNewContact() {
var parameters = {};
//Set the Parent Customer field value to “Contoso”.
parameters["parentcustomerid"] = "2878282E-94D6-E111-9B1D-00155D9D700B";
parameters["parentcustomeridname"] = "Contoso";
parameters["parentcustomeridtype"] = "account";
//Set the Address Type to “Primary”.
parameters["address1_addresstypecode"] = "3";
//Set text in the Description field.
parameters["description"] = "Default values for this record were set programmatically.";
//Set Do not allow E-mails to "Do Not Allow".
parameters["donotemail"] = "1";
// Open the window.
Xrm.Utility.openEntityForm("contact", null, parameters);
}
Example: Use window.open to open a new window
The following sample sets default values on several different fields and shows how to use encodeURIComponent to encode the value of the extraqs parameter. If you use the window.open method, you can control the features of the window that is opened.
function OpenNewContact() {
//Set the Parent Customer field value to “Contoso”.
var extraqs = "parentcustomerid={F01F3F6D-896E-DF11-B414-00155DB1891A}";
extraqs += "&parentcustomeridname=Contoso";
extraqs += "&parentcustomeridtype=account";
//Set the Address Type to “Primary”.
extraqs += "&address1_addresstypecode=3";
//Set text in the Description field.
extraqs += "&description=Default values for this record were set programatically.";
//Set Do not allow E-mails to "Do Not Allow".
extraqs += "&donotemail=1";
//Set features for how the window will appear.
var features = "location=no,menubar=no,status=no,toolbar=no";
// Open the window.
window.open("/main.aspx?etn=contact&pagetype=entityrecord&extraqs=" +
encodeURIComponent(extraqs), "_blank", features, false);
}
See Also
Open forms, views, dialogs and reports with a URL
openEntityForm
Configure a form to accept custom querystring parameters