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