Extending Microsoft Dynamics™ C RM 4.0

1. Extending Microsoft Dynamics™ C RM 4.0 Chapter 7 – Application Event Programming

2. Overview • Use form and field events. • Reference Microsoft Dynamics CRM form values. • Set event dependencies. • Apply best practices when writing client-side code. • Debug client-side code. • Use DHTML within client-script. • Reference code in external files. • Access external data with client-script. • Access Microsoft Dynamics CRM Web services from client script.

3. Lesson: Form and Field Events • Script events occur when a form loads or is saved and when field values change. • Use available events to script custom behavior. • Reference values in Microsoft Dynamics CRM fields when scripting events. • Set field dependencies for events.

4. Form and Field Events • Form types used to view and edit entities: • Create • Update • Read-Only • Disabled • Bulk Edit • Undefined • Access forms using the crmForm object. • Query form type using FormType property.

5. Form and Field Events • Form Type is important: • Code added to an event is used for every form type. • Code is used for all clients. • Includes Laptop client in offline mode. • Not all form types display the same fields. • Check the form type before including logic that is dependent on form type.

6. Form and Field Events • Global Functions • Determine the state of the client • IsOnline • IsOutlookClient • IsOutlookLaptopClient • IsOutlookWorkstationClient

7. Form and Field Events Global Functions Example – JScript /* Only do this when we are online */ if (IsOnline()) { /* Code that requires connectivity goes here */ alert("Code would execute here"); } else { alert("This feature is not available offline"); }

8. Form and Field Events • Supported Form and Field Events • Define events that occur when you: • Load a form • Save a form • Change a value in a field • Referred to as: • OnLoad events • OnSave events • OnChange events

9. Form and Field Events • OnLoad Event • Fire when the form for which the event is defined loads. • Perform actions such as: • Disable fields programmatically • Show alerts • Set default data • Set up data that OnChange events may need later • OnSave Event • Fire when any action causes the system to save the form. • Fires before data is submitted to the platform and committed to the database. • Typically, used to perform validation logic.

10. Form and Field Events • OnChange events • Fire whenever the DataValue of a field changes and focus is lost. • Do not fire until the focus has left the control. • Are typically used to perform validation, data cleansing, or formatting.

11. Lesson: Accessing Microsoft Dynamics CRM Data Fields • All Data Fields have a DataValue Property • Get/set property • Use to reference CRM values when scripting events • Provides a data object • Uses standard JScript types • Empty fields generally return NULL

12. Accessing Microsoft Dynamics CRM Data Fields • Simple field types • Text/Memo • Integer • Duration • Float/Currency • Date/Time • Boolean

13. Accessing Microsoft Dynamics CRM Data Fields • Complex Field Types • Picklists • Returns a number as a string. • Treat this value as a string or use parseInt() to convert it to a number. • Methods exist to add or remove options – but this must always be used to reduce (or add back) the available options defined for the picklist in the platform. • Invalid options will be saved as the default value. • Lookup • Returns an array of lookup objects. • E-mail • Returns a string of HTML.

14. Lesson: Setting Event Dependencies • Define the form fields that custom code depends upon. • System uses this information to prevent users from removing fields from the form that would break the custom code. • To define an event’s dependencies: • Navigate to the Event Detail Properties dialog. • Move the fields required by the event script to the Dependent fields box. • Click OK.

15. Lesson: Best Practices in Writing Client-Side Code • Comments • Distinguish your code from any other code. • Use the /* */ commenting style. • Existing Scripts • Be careful not to overwrite. • Add-ons to CRM may inject code into the form. • Checking FormType • Check for the form and client where the code is executing. • Test your code in all scenarios. • Write special conditions to accommodate the nuances of each form. • Developing Code in an Editor • Develop scripts within an editor. • Paste them into the appropriate form.

16. Debugging Client-Side Code • Verify the following settings on the development computer: • Internet Explorer: • Load page content = “Every time” • Friendly errors = off • Script debugging = on • CRM Dev Errors = On (through web.config) • Verify that you are debugging the Latest Code. • Enable the Every visit to the page feature. • Set the Script Debugging and Friendly Errors Options.

17. Lab 7.1 – Creating Hierarchical Picklists • Sales Department wants to be able to categorize its calls by type. • As one call type is selected, the call description field needs to be filtered to only show the applicable description. • A script in the telephone call activity will only shows valid values in the Call Description field based on the Call Type. • The available values for Call Description must be changed when the Call Type field is modified. • When an existing record is loaded into the form, the available Call Description values must be correct. • If the Call Type field does not have a value selected, the Call Description field will be disabled.

18. Lesson: Using DHTML • Access to the DOM (Document Object Model) • Use the DOM to access the CRM fields. • Write DHTML to perform actions on the field or form. • Using the DOM for undocumented scripting • If not documented in the CRM Client-side SDK it is strictly unsupported by Microsoft. • Undocumented properties and methods are untested. • May not survive an upgrade, hotfix, or service pack. • Significant unexpected results can occur.

19. Using DHTML • Unsupported DHTML customizations: • Display popup messages • Hide fields • Change the color and appearance of fields • Use attachEvent() to add custom event handlers • Actions to Avoid • Moving or removing elements from the DOM. • Modifying the form controls. • Reusing undocumented crmForm functions. • Anything that affects the structure of the DOM.

20. Using DHTML • Using attachEvent to add custom event handlers to DHTML elements on the form. • Unsupported. • Form elements may not persist from version to version. • Form elements may be changed by hotfixes. • Microsoft Dynamics CRM code may strip your custom events while the form is in use.

21. Using DHTML AttachEvent Example – JScript 1 of 2 function CompanyName_GlowField() { /* The Event's SrcElement will be the element that fired the event in this case, it will be the CRM form element */ event.srcElement.runtimeStyle.backgroundColor = "#ffdddd"; }

22. Using DHTML AttachEvent Example – JScript 2 of 2 function CompanyName_RevertField() { /* Runtimestyle will automatically revert the style back to what it was prior to our code changing it. */       event.srcElement.runtimeStyle.backgroundColor = ""; } /* Hook up events to the Account Name field */ crmForm.all.name.attachEvent("onmouseover", CompanyName_GlowField); crmForm.all.name.attachEvent("onmouseout", CompanyName_RevertField);

23. Lesson: Developing Code with External Files • Development practice only: • Not Supported by Microsoft Dynamics CRM Developer Support. • Should not be used in Production Environment. • Accelerates the development and testing process. • Promotes code reuse. • Best Practices • Names of functions and variables must be unique across add-ons, and • Names must not override any Microsoft Dynamics CRM methods or variables. • Using OnLoad to call functions: • Best to use to include the script only and not to call other functions .  • Write code that waits for the functions to be available.

24. Lesson: Request External Data • Can retrieve data from anything accessible through JScript and ActiveX • IFRAME • XML Object • RDO object • Use AJAX to perform synchronous server requests to get data from the server • Not a Microsoft Dynamics CRM feature or technology

25. Request External Data • Request External Data • Declare the ActiveX Object to get the data. • Configure the ActiveX Object. • Tell the ActiveX Object to get the data. • Ask the ActiveX Object for the data. • Consume the data through Jscript.

26. Request External Data

27. Request External Data Example var objHttp = new ActiveXObject("Microsoft.XMLHTTP"); objHttp.open("GET", url, false); objHttp.send(); var oXml = objHttp.responseXML; alert (oXml.selectSingleNode("root\value").text);

28. Accessing Microsoft Dynamics CRM Web Services • Using Client-side JScript Code • Microsoft Dynamics CRM On-premise • Create a Web Service and connect using client-side Jscript. • Microsoft Dynamics CRM Live • Use XMLHttp requests to the Microsoft Dynamics CRM Web Services. • Use the global function GenerateAuthenticationHeader to set authentication details

29. Lab 7.2 – Using XML Request Request external data to modify the form. Pass the postal code to the Web page using a query string, validate and return XML with the State and City. Use an error node to handle errors.

30. Review Use form and field events. Reference Microsoft Dynamics CRM form values. Set event dependencies. Apply best practices when writing client-side code. Debug client-side code. Use DHTML within client-script. Reference code in external files. Access external data with client-script. Access Microsoft Dynamics CRM Web services from client script.

31. Test Your Knowledge Perform the Test Your Knowledge quiz.