The posts Dialogs Part 1 and Dialogs Part 2 talk about the new Dialogs feature in Microsoft Dynamics CRM 2011. Dialogs support the usage of Variables and Input Arguments. In this post, I will explain what they are and some tips on using them. The Dialog designer provides a section for defining variables and input arguments as seen below:
Figure 1: Section for variables and input arguments.
What are Variables?
Variables are used for temporary data storage during the lifetime of a dialog. You can create a new variable by clicking on the Add hyperlink in the Variables section seen in Fig. 1. Each variable has a name, type and value. While creating a variable, you specify these properties as shown in the Fig. 2 below. Here we have created a variable called CustomerName, which will store a Single Line of Text, and has an initial default value of John Doe. The default value is the initial value of the variable.
Figure 2: Creating a new variable
What are Input Arguments?
Input arguments are used along with Child Dialogs. Child dialogs are used in situations in which you would like to transfer control to another dialog. The dialog which transfers control is called the Parent Dialog and the dialog which gets control is called the Child Dialog. Consider a situation that you want to create multiple dialogs where the last set of steps is the same. For such cases, it will be a good idea to create a separate child dialog which has the common steps. This way, you won’t have to edit multiple dialogs if some change is needed in the common steps. You can just change the child dialog and all the parent dialogs will not need modification. While transferring control from parent dialog to a child dialog, you might need to transfer some data. This is accomplished by using Input Arguments. While authoring a dialog, you can specify that it is a child dialog by editing the properties in Available to run section (see Fig. 1) as follows:
- Enable the As a child process option
- Disable the As an on-demand process option
At this time, you can create input arguments to specify what data is expected from the parent. For creating an input argument, you can click on the Add hyperlink in the Input Arguments section seen in Fig. 1. Like a variable, an input argument too has a name, type and value. The user interface to configure the properties of an input argument is very similar to the one used for creating a variable. For an input argument, the default value will be used by the child dialog in case the parent dialog does not specify a value for it.
While authoring the parent dialog, you need to link it to the child dialog. You can do this by adding a Link Child Dialog step through the designer. You can look up the child dialog to link to. Figure 3 shows a link child dialog step added at the end.
Figure 3: Linking to child dialog
Also, you can set the linkage properties by clicking on the Set Properties button (as seen Figure 3). In this set properties UI, you can specify the value to use for each of the input arguments. Note that you can also use a dynamic value like a variable or the value of one of the fields of the CRM record that the dialog is running on. The only caveat is that the source value should be of the same data type (or can be converted to the target data type). Figure 4 shows a sample linkage properties screen. Here the Name input argument (displayed as String_Name) is being passed the Full Name of the Primary contact associated with the current account (the account instance on which the dialog is run), the Age input argument is being passed the response that the user enters for the Request for age prompt, and the DiscountRate input argument is being passed the value of the variable DiscountRate defined in the parent dialog.
Figure 4: Setting properties for child dialog
Apart from the purpose of use, variables and input arguments have common behavior in the way they are referenced in the rest of the dialog. In this section, I will go through additional details that are common to both of them. As mentioned earlier, each variable/input argument has a name, type and value.
- Name: The name of a variable or input argument must be unique within the dialog. Also, the same name cannot be given to a variable and an input argument. The name is limited to 1000 characters in length and can only have alphabets, numbers and the underscore (“_”) character.
- Type: There are three supported types for a variable or input argument. It can be a Single Line of Text, a Whole Number, or a Floating Point Number. Whole number supports values in the range of -2,147,483,648 and 2,147,483,647. Floating point number supports values in the range -100,000,000,000 and 100,000,000,000.
- Value: When creating the variable, you specify an initial default value for it. You can change its value by assigning it a result of some operation like Append With (in case of a variable to type Single Line of Text), or assigning a value typed in by the person executing the dialog. You can use/refer to the value of the variable wherever data needs to be specified: like creating/updating records and displaying prompt. You can go through the Lead Scoring sample blog for a detailed example of lead scoring which leverages variables. Though this makes more sense for variable, it applies to modifying the value of an input argument within a child dialog as well. When assigning a value to variable or input argument, the data type of the value being assigned has to be compatible with the type of the variable or input argument. Below table specifies the possible combinations:
Variable or input argument type
Supported types of values being assigned
Single Line of Text
Single Line of Text, Whole Number, and Floating Point Number
Whole Number, and Floating Point Number (after rounding)
Floating Point Number
Whole Number, and Floating Point Number
1. Be careful while deleting a variable or an input argument while authoring a dialog. If it is being referenced by some other steps (like a Prompt and Response step), then those steps will get disabled. So, it is advisable to remove the references to the variable/input argument before deleting it.
2. Once a variable or input argument has been created, you cannot change its type.
3. The link to the child dialog has to be the last step in the parent dialog. The “link child dialog” step will transfer the control to child dialog. While running the parent dialog, you will not be able to go back to the previous step (in the parent dialog) once the control is transferred to the child.
4. There is no overflow protection while using numeric variable and input arguments. This will have to be handled during authoring itself.
5. If you change the input arguments used in a child dialog after the parent has been published, then the parent dialog will not pick up the changes automatically. This may result in an error while executing the parent dialog.
Thanks for reading this post!