Hello everyone,

In this blog post, i would like to discuss about the importance of “Replacement Keys” in USD. This is especially important for the beginners in USD development.

To keep it simple, “As a good practise when using Replacement Parameters in USD, make sure to use appropriate Replacement Keys”. Ok, sound good. But, what if we don’t use them? To answer it, first we need to understand how the code written in RunScript and RunXrmCommand(and wherever Replacement Parameters are used) gets Exected.

Lets assume we have an action call to set some values on case form for 3 fields. Out of these 3, we have one field “new_incomingphonenumber” whose value is set from the context’s “PhoneNumber” Replacement Parameter.

Following is the action call’s script:

Xrm.Page.getAttribute(“description”).setValue(“[[$Context.CallNotes]]”);
Xrm.Page.getAttribute(“new_incomingphonenumber”).setValue(“[[$Context.PhoneNumber]]”);
Xrm.Page.getAttribute(“new_sessionid”).setValue(“[[$Session.ActiveSession]g]”);

 

When case form loads and all keys exists in the $Context and $Session, all 3 fields gets it’s data populated.

When we look into “Debugger”, this  action call’s “Action Data” following will be the script that was executed.

Xrm.Page.getAttribute(“description”).setValue( “Compalint Regarding ABC Product”);
Xrm.Page.getAttribute(“new_incomingphonenumber”).setValue( “123-456-7890”);
Xrm.Page.getAttribute(“new_sessionid”).setValue( “8e3cdc83-2dd7-462a-b428-6b6a831b086e”);

One main thing we have to observe here is, all replacement parameters are replaced with their corresponding values.

Let’s assume we don’t have “PhoneNumber” key in the $Context.

In this case, we get the following error in the debugger when the action call runs:

Action Call# 1

Source:Event(Ticket:BrowserDocumentComplete)
Name:Populate Ticket Default Values
Application:Ticket
Action:RunXrmCommand
Action Data:Xrm.Page.getAttribute(“description”).setValue(“Compalint Regarding ABC Product”);
Xrm.Page.getAttribute(“new_incomingphonenumber”).setValue(“[[$Context.PhoneNumber]]”); 
Xrm.Page.getAttribute(“new_sessionid”).setValue(“7103ada9-c2ba-4fe7-b246-82fc5864407e”);
Parameters:”frame”=””
“url”=”http://crmserver/FunStuff/main.aspx?etn=incident&id=&extraqs=&pagetype=entityrecord#618247925”

Condition:
Condition Result:ActionFailed
Exception Details:Not all parameters in the action call RunXrmCommand are available, stopping the action call. The parameters are : Xrm.Page.getAttribute(“description”).setValue(“Compalint Regarding ABC Product”);
Xrm.Page.getAttribute(“new_incomingphonenumber”).setValue(“[[$Context.PhoneNumber]]”); 
Xrm.Page.getAttribute(“new_sessionid”).setValue(“7103ada9-c2ba-4fe7-b246-82fc5864407e”);
======================================================================

 

Due to this error, none of the field values are populated. Following will be the “Action Data” for this action call.

 

If we check the “Action Data”, “Phone Number” key is not replaced.

Xrm.Page.getAttribute(“new_incomingphonenumber”).setValue(“[[$Context.PhoneNumber]]”); 

Even though one replacement parameter is not replaced, we expects to see at least first field gets their data populated and remaining fields are blank. However, this is the difference: “In USD, scripts are first get parsed as regular text with all of the Replacement Parameters before they get executed”.  In our case, USD tried to replace “[[$Context.PhoneNumber]]” with it’s value from $Context and it couldn’t find the “PhoneNumber” key. When Action Call runs, it throws an error due to this.

To solve this, we have to use appropriate “Replacement Keys” when using “Replacement Parameters”. In our case, it will be a “+” sign like “[[$Context.PhoneNumber]+]”

Xrm.Page.getAttribute(“description”).setValue(“[[$Context.CallNotes]+]”);
Xrm.Page.getAttribute(“new_incomingphonenumber”).setValue(“[[$Context.PhoneNumber]+]”);
Xrm.Page.getAttribute(“new_sessionid”).setValue(“[[$Session.ActiveSession]g+]”);

So, is it the “+” only character which we need to use to avoid these kind of issues? Answer is No. “+” is useful to avoid non-existent key issues and to replace it with empty strings. As I mentioned just before, USD parses your entire script before it gets executed. So, what if one of your replacement parameter has URL or quote or line breaks in it’s value? When these values exist, action call fails executing the script as we haven’t escaped these characters and script becomes invalid.

Check out the following MSDN article which has the list of Replacement Keys and their purpose.

https://msdn.microsoft.com/en-us/library/dn864934.aspx#ReplacementKeys

One more thing, we can use combination of these replacement keys to benefit from multiple scenarios. If we have a look at the following line of code which we used to set Session Id, we used “g+” replacement key. “g” being used to get Replacement Parameter from Global Session and “+” replacement key replaces it with empty string when that replacement parameter doesn’t exist.

Xrm.Page.getAttribute(“new_sessionid”).setValue(“[[$Session.ActiveSession]g+]”);

This is the post which mainly targeted for beginners in USD development and I hope it helps.!!

Cheers

Vikranth