CRM Rules! User Guide. Version Prepared October, 2012 By: David L. Carr, President, Visionary Software

Transcription

1 CRM Rules! User Guide Version Prepared October, 2012 By: David L. Carr, President, Visionary Software

2 Table Of Contents Chapter 1: Overview... 5 What s a CRM Rule?... 5 What Can I Do With CRM Rules!?... 5 Glossary of Terms... 7 Chapter 2: Form Help... 8 Rules Definition... 8 CRM Rules Status Values Rule Types Rule Conditions Logical Operators Automatically Created Conditions Conditions Rule Actions Actions Rule Action Types Action Type Categories Visual Actions Explained: Hide/Show Fields, Sections, Tab Set Value Actions Explained: Set Field Value Process Actions Explained Technical Actions Explained Individual Action Types Explained Enable All Fields, Disable All Fields Hide Field, Show Field, Enable Field, and Disable Field Set Focus Fire On Change Always Submit Field Field Evaluation Invoke Process Dialog... 32

3 Run Workflow Run Rule! Format Phone Number Expand Tab, Collapse Tab, Show Tab, Hide Tab Hide Section, Show Section Required Fields Custom JScript Set Option Set List Set Field Value Action Types Set Field to Now Fire On Change Set Field to Null Set Field to Mathematically Derived Value Example Equation Set Field to Derived String Concatenation value When to Run Rules Set Field Value (to a constant) Set Field to Other Field Value Set Field Value to Field on Other Entity Copy Fields From Lookup Entity CRM Rules! Technical Architecture Overview CRM Rules Entity Summary Sub Area: Rule Management Sub Area: Rule Creation Sub Area: Rule Deployment Sub Area: Rule Details Sub Area: Rule Metadata Sub Area: Rule Reference Your CRM s Metadata Inside CRM Rules! Refreshing Metadata If your Lookup values don t refresh... 58

4

5 Chapter 1: Overview CRM Rules! is a managed solution add-on product from Visionary Software that enhances the toolbox for CRM 2011 system administrators by enabling them to modify CRM form behavior without writing JavaScript code.. This document is designed to assist CRM Rules! clients design and build rules. Our CRM Rules! engine will then generate JavaScript code and deploy and publish this code to the target form. Hint: Check the Table of Contents for specific topics. Some of the most frequently asked are visible in that list, for example: Refreshing Metadata When you add new fields to a CRM entity, or add or change option set values, or add sections or tabs to forms anything that you might want to write a rule for - to get them into CRM you have to click the Create/Update Entity Data button. What s a CRM Rule? A CRM Rules! user uses our custom forms (built in CRM) to specify criteria, by defining conditions, and the actions to take if those conditions are true, or alternatively, actions to take if the condition set is false. One CRM Rule affects the form behavior for one or more forms on an entity. A rule consists of five main components: CRM Rule Components Rule Header IF Conditions THEN Actions ELSE Actions Rule Event Handlers Description Identify the entity and a function name One or more conditions, such as IF Contact Type = Customer One or more actions that are taken if the Condition(s) are true One or more actions taken if the Condition(s) are false. Event handlers specify when the rule should run. Values are onload of a form, onsave of a form, or onchange of a field value. What Can I Do With CRM Rules!? Our target users are business analysts, CRM System Administrators, and developers who want to modify CRM form behavior. Out of the box, using the CRM Customization tools, you can add entities, fields, views, and modify form layout. But, until now, you must learn and code JavaScript to modify the behavior of the form. Now, with CRM Rules!, you can expand your toolbox to include over 30 actions that you can inject into your forms. By form behavior, we refer to anything that happens in response to data or events, like: - Showing and hiding fields, sections, and tabs. - Changing a field to be required, based on the data on the form - Creating hierarchical picklists, or option sets - Setting field values Visionary Software, Company Confidential, All Rights Reserved, Oct 2012 v Page 5 of 59

6 Now, you can use CRM Rules! to implement these features without laboriously coding JAvascript. For example, with CRM Rules! you can do things like: - Conditionally set a field to be required. If the Contact Type = Customer, require an address. - Format a phone number immediately after you enter the phone number. - Derive the Name of the entity from the value of several fields on the form. Very useful for creating a standard naming convention: see all Hot Opportunities by just looking at the name. - Perform mathematical calculations, conditionally, when fields change. If you use custom entities and want to calculate price times quantity, not a problem - You can now even Count Children! Automatically update and display in your Account header the number of Contacts and Opportunities linked to this Account. o And, if you use the Count Children feature, you could then solve the Not In problem, and find all Accounts with no Opportunities, or no Contacts! Something you cannot do in CRM Advanced Find today. - Our latest feature lets you Sum Fields Across Child Entities! You can now calculate the total expected value of all opportunities tied to each account. - Conditionally set one of several fields to be required. If the is blank and the Main Phone is blank, disallow the save and display an error message. - Make only certain option set values appear, again based on any conditions. If the Account Status is Suspect, do not allow the user to select Hot from the priority field. o You can implement hierarchical picklists (option sets in CRM): make the State / Region list dependent on the Country that is selected. - You can copy many fields from one entity to another, to show the Product Master custom field values on the Order Product form, to help your users know more about their products with less clicking. - Taking this further, when they choose the product, you can change the look of the entire form: hiding tabs, showing one section out of many in one tab, etc. - You can show fields or hide them. If the contact is a prospect then hide the Account Manager field. - Combine actions in your rules to then show that field AND make it required if the contact is a customer! - Conditionally run workflow, so you only run the workflow when it has something to do. This makes that workflow left nav bar item a useful history of automation applied to this record, instead of a cluttered mess. - Conditionally Invoke a Process Dialog, based on data! OOB, you can only invoke a process dialog when a user clicks a button. Now, you can run it based on the change event of any field on your form. This could enable you to create an incredibly extended form that guides the user down a problem-solving path, without cluttering your main form. Visionary Software, Company Confidential, All Rights Reserved, Oct 2012 v Page 6 of 59

7 Glossary of Terms Term Meaning/Usage Rule A collection of conditions and actions that affect CRM 2011 form behavior. Rule Type We have 6 Rule Types, listed in a table below, that generate different Javascript code, and require different information from the rule designer in order to be executed. Condition Set One Rule Definition can have many conditions attached to it. This is referred to as the Condition Set. Action Type Also referred to as a CAT (CRM Rule Action Type), this defines the desired form behavior. Each Action Type can require different information from the rule designer, and the Action form dynamically changes to ask for just what is needed. OOB Out of the box, typically referring to the standard functionality contained within CRM. CRM Rules! greatly extends the capabilities of a System Administrator from what exists OOB. Rule Event In CRM, a form can have many events (onload, OnSave, or OnChange of all fields.) You Handler can also specify many things that happen when a certain event occurs: these are called event handlers. You specify when rules run with Rule Event Handlers. We then create CRM event handlers from this data. Visionary Software, Company Confidential, All Rights Reserved, Oct 2012 v Page 7 of 59

8 Chapter 2: Form Help This section is designed to assist a user in filling out CRM Rules! forms. These forms are presented in the logical order of when you might encounter them while building a rule. Rules Definition The Rule Definition entity is the header for a rule. Each rule has one Rule Definition record. Rule Definition identifies the entity, function name, status, rule type and rule number.. As each rule definition refers to one rule, we use the terms interchangeably, but a rule really consists of other things other than just the rule definition entity. A rule can have many conditions; and a condition can be used in more than one rule. This is a many-tomany condition that is resolved through the Rule Condition entity. This links a condition with a rule. Similarly, a rule can have many actions, and an action can be used in more than one rule. This many to many condition is resolved through the Rule Action entity. The Rule Action entity, then, links an action to a rule. The Rule Definition form is a lengthy form, the top of which appears as follows. Below the screen print we discuss each of the fields on this header portion of the form Visionary Software, Company Confidential, All Rights Reserved, Oct 2012 v Page 8 of 59

9 . Rule Definition Field Name Name Entity Rule Type Function Name Comments Rule Number Rule Status User Defined Status Explanation Describes the rule in English terms (FYI only) Defines the CRM entity, custom or system, where this rule runs. See the table below to see the Rule Types that are currently supported. Each rule type requires different information from the designer of the rule so that we can code the appropriate JavaScript. Each JavaScript function in CRM has a function name. This is technically what is called when this rule is executed. A field to capture more information about the rule that will not fit in the Name field. You can also use Notes to record other free text information about the rule. Comments and notes are for informational purposes only. This allows the user to specify a unique number for each rule. This allows you to map a CRM Rule to a spec document, for example. This field is for informational purposes only. See the table below for the CRM Rules! Status values, and their meaning. We have added an option set field into the Rule Definition form so that you can specify an alternative pipeline. You can use this, for example, to specify that a rule has passed your internal QA process, or not. Visionary Software, Company Confidential, All Rights Reserved, Oct 2012 v Page 9 of 59

10 CRM Rules Status Values Each CRM Rule moves from Draft status, to Validated, Ready to Deploy and Deploy. These status values can be set either manually, or by clicking one of the four buttons on the CRM toolbar ribbon that appears when the Rule Definition form is loaded. Status Value Draft Validated Ready to Deploy Deployed Validation Error Explanation A rule that is in progress. These new rules do not yet exist in the CRM form. This is similar to a Disabled status for a workflow. When the user click the Validated button, or sets a rule status to Validated, we review your conditions to ensure they make sense, and then degenerate the JavaScript code and Event Handlers needed to carry out your rule. You create rules one at a time, but deploy them one entity at a time. This status allows you to mark rules as ready to be deployed to the CRM target form. Only rules in Deployed or Ready to Deploy status are sent to the CRM form. This status indicates that the JavaScript for this rule has been entered into the CRM form, and published, and now active. This rule will now be implemented on the CRM form(s) on the specified entity. IF your rule contains a syntax error (for example, unbalanced parenthesis), your rule will be placed in this status, and will not be deployed to CRM until you fix the error. Visionary Software, Company Confidential, All Rights Reserved, Oct 2012 v Page 10 of 59

11 Rule Types CRM Rules! currently contains the following Rule Types. The IF/THEN/ELSE and CASE rule types allows a rule designer to specify more than 30 actions to take when the specified conditions are true pr false. Rule Type IF/THEN/ELSE Standard Rule CASE Custom JavaScript Count Children Sum Values Across Children Clone Usage The typical CRM Rule involves a series of IF conditions that if True will cause the THEN actions to be executed. If the set of conditions evaluates to false, the ELSE Actions will be executed. Also known as Switch/CASE this rule evaluates an option set and allows you to specify a different action depending on which value exists in this field on the current record. This enables you to more quickly defines rules based on an option set value. (Anything you can create in a CASE rule type can also be created in the IF/THEN/ELSE rule type.) Allows you to paste in JavaScript code that you have manually written, outside of CRM Rules! This enables you to define a complete library of rules that are in effect for a given entity. Allows a rule designer to count the number of records linked to a parent. For example, you can count the number of Contacts linked to each Account. When you deploy this rule type, you can specify if you want this to run on all existing data. This Rule Type uses a post-save plug-in that reads our custom entities to do these operations. The rule designer can specify a field to sum, and the parent entity field to store the summation. For example, you can total the sum of all opportunities linked to an account. When you deploy this rule type, you can specify if you want this to run on all existing data. This Rule Type uses a post-save plug-in that reads our custom entities to do these operations. This rule type requires a bit of customizations outside of CRM to define a toolbar button that will execute the Clone action. This Clone rule type allows the rule designer to define the fields that are cloned from one entity to another. Note: this rule type is very similar to CRM OOB Relationship Mapping. It was introduced to allow one of our clients to clone the same record type, e.g., create a new account record from the existing account record. Visionary Software, Company Confidential, All Rights Reserved, Oct 2012 v Page 11 of 59

12 Rule Conditions A rule can have many conditions. One of the important design features of CRM Rules! is the ability to re-use conditions across many rules. Therefore, we have built the Rule Conditions table to identify the conditions applicable to each rule, called the Condition set. The Rule Condition entries appear in a grid on the Rule Definition form. You can see above that there are three conditions, linked by OR operators. This means that if any of these three conditions are true, then the THEN actions will be taken. If ALL of them are false, then any ELSE actions will be taken, Logical Operators Conditions are about one field value equaling a certain value. You can combine these conditions in a number of ways. (And, given you can use a Run Rule Action to nest rules, you can structure an equation of any complexity.) Visionary Software, Company Confidential, All Rights Reserved, Oct 2012 v Page 12 of 59

13 The first field you enter in the Rule Condition form is to select, or create, one condition. You order the conditions by sequence number which is only important, and then critically so, when using the complex Pre Condition Values. Symbol Usage ( IF you have mixed AND/OR conditions, you typically should use parenthesis to ensure proper order of operation. OR If any conditions linked by OR are true, the result is true AND If ALL conditions linked by AND are true, the result is true OR ( Used to create conditions like (A and B) or (C and D) AND ( Used to create conditions like (A or B) AND (C or D) (( To allow nested conditions OR (( OR with nested conditions AND (( AND with nested conditions While this can t cover all possible combinations, please remember that with the Run Rule Action, you can have a set of conditions lead to rule run that has a set of conditions So you should be able to match any condition complexity. On the Rule Condition form, you can specify the order in which conditions are evaluated, fire, and how they are related (and/or). Each condition tests one or more field values. If all conditions are true, then the Then Actions listed are executed. If the condition set is not true, then any Else Actions are executed. The condition set is all of the conditions linked to one Rule Definition. These conditions can be linked via OR, AND, and uses parenthesis to ensure the proper order of operation amongst the conditions. You define condition sets by selecting a condition, and linking it to the other conditions, on the Rule Conditions form. Visionary Software, Company Confidential, All Rights Reserved, Oct 2012 v Page 13 of 59

14 Visionary Software, Company Confidential, All Rights Reserved, Oct 2012 v Page 14 of 59

15 The Rule Condition form appears as follows when you Add New Condition. On the Rule Condition Form are the following fields. This table identifies how to fill these fields in. Rule Condition Field Name Condition Sequence Number Your Rule Number Rule Condition Name Pre Condition Value Post Condition Parens Explanation Select or build one condition. By selecting it here, you are linking that condition to this rule. Said another way, a rule can have one or more conditions, that you select from this lookup field. An optional field that will determine the order in which your conditions are applied. It doesn t make any difference if all conditions are linked by OR or AND, but if you have mixed conditions, or use parenthesis, this number becomes crucial. The grid of Rule Conditions displayed on the Rule Definition form is sorted by this number, for easier visibility into your condition set. An optional, FYI only, field. Often, specs have rules defined by number, so that you can more easily discuss them, or report bugs, etc. Rule numbers are defined as a quick search field, so using rule numbers enables you to quickly search and find a specific rule. This displays on the grid, but is for informational purposes only. We have built code behind that form that will automatically derive this name field based on the condition and sequence number This links together multiple conditions in your condition set. See the table below for a list of possible values here. As the name implies, these conditional values are applied before the condition. In other words, if you have two conditions, and you want to combine them via an OR operator, then you would specify OR as the pre condition value on the second condition, because the syntax should be Condition OR Condition. If you use parenthesis in the pre-condition value field to create complex conditions, close the parenthesis using this field. Visionary Software, Company Confidential, All Rights Reserved, Oct 2012 v Page 15 of 59

16 Automatically Created Conditions When you run the CRM Rules! setup option for an entity, we automatically generate many conditions. We generate conditions for each value in all option set fields in that entity. We also generate conditions for some values from some lookup fields. There is a setting in the CRM Rules! Setting entity that determines how many conditions we create for lookups. The default setting is 50. So, any lookups that have fewer than 50 records will have conditions created for those. If you have lookups that have more than 50 values, and you want to create conditions for all of them, set this setting to the number of records in that field you want to create lookups for. You can also manually create lookup entries in the Entity Field Values table if you want to create conditions on a specific lookup value, in those fields that have more than 50 distinct values. You can select any of these pre-built conditions from the Condition lookup button on the Rule Condition form. Special Global Conditions (Form_Create, e.g.) We also automatically create four special conditions that you can use just by selecting them. When you create a new condition, and enter the entity and select a field, that list is filtered by the entity you entered. We have four what we call global conditions that are not entity specific. These conditions allow you to, e.g., only perform an action when the record is being created. To create a rule that will only run the THEN actions when the form is loaded because the user clicked on the Add New button, the FORM_CREATE mode, a) create a new condition, and click on the Field Name lookup. b) Enter the word Form in the Search box. c) Uncheck the filter by related entity box. You should see the following conditions: Visionary Software, Company Confidential, All Rights Reserved, Oct 2012 v Page 16 of 59

17 The rest is easy. If you want your THEN actions to fire only when the user is creating a New record, then select the Form Type equals FORM_TYPE_CREATE condition, and add it to any other conditions you may need with an AND condition. Obviously, if the actions should only fire when the record is being updated, and has already been saved once), then you can use the FORM_UPDATE condition. Read Only will let you know if the form type is one of the new read-only ones, and if the record is disabled, you can write a rule that only fires in that instance by using the FORM_TYPE_DISABLED condition. ONE ENTITY for the Rule Definition, Conditions, and Actions Because of how CRM treats 1:N and then N:1 conditions, we can pass the entity from the Rule Definition entity down to the Rule Condition entity, but we re unable to pass the entity Up to the Condition entity. So, when you create a new Condition, it asks you for the entity again. (Please remember that you can type in the first few characters of a lookup fields, in it will usually resolve it for you, to reduce the time this takes.) However, you cannot currently execute a condition built in one entity for a Rule Definition in another entity. If you, for example, select the Account entity in the Rule Definition record, and save it, that will be passed to the Rule Definition entity. If you then select a new Condition, it will ask you for the entity. If you select Contact instead of Account, you ll be able to build and save that Condition. However, because we check the box that applies the entity filter, you can t see the Condition you just built on a different entity. The fix is to rebuild the rule in the correct (in this case, Account), entity. Similarly, you can only execute Actions on the same entity that you built the Rule Definition record on. If you try to build it against a different entity, you can built that action, but you won t be able to select it in the Rule Action lookup grid. The exception to this rule is that you can use global conditions in a rule written against any entity. So, while this may change in the future, right now, the rule is: one Entity per Rule! Visionary Software, Company Confidential, All Rights Reserved, Oct 2012 v Page 17 of 59

18 Conditions A Rule (Rule Definition) can have many Rule Conditions. Each Rue Condition links to one Condition. When you add a new Rule Condition, your first step is to click on the Condition lookup icon. Clicking on that Condition lookup icon opens the Condition Lookup View, which displays all of the conditions that have been either built when you clicked on Create/Update Entity Data, or created by you. In the screenshot above, you can see that I can select from among 666 conditions that have been created. You can use the search field, and use wildcards, to find an existing condition. If you do not find the condition you are looking for, then click the New button to create a New Condition. When you create a new Condition, this form appears. The table below identifies what to enter in each field. Visionary Software, Company Confidential, All Rights Reserved, Oct 2012 v Page 18 of 59

19 Condition Field Name Entity Field Name Operator Owner Name Field Type Explanation Select the same entity that you are building this rule for from this lookup field. Once you enter the entity, that is the filter for this filtered lookup for the Field Name field, so that you only see Fields from this entity. (If the desired field is not there, you probably added it to CRM since the last time you clicked on the Create/Update Entity Data button, so to fix just click the entity hyperlink to open that entity record, and click that button. Wait until the Deployment HJistory grid shows that the conditions were created, then reload this form, your field name should now appear.) When you fill in the field name, that runs a rule that prefills the field type on this form from the Entity Fields table. That field type value is another filtered lookup that restricts the list of operators to only those appropriate for this field type. Your user name is prefilled as the creator, and thus owner, of the rule. You can change this if desired, it is not critical in the building of our rule code. The Condition Name is prefilled from the field name and operator and field value selected. You may modify this name, but in most cases we suggest you don t, as this standard naming convention makes existing conditions easier to find, and re-use. As stated above, this field is derived from the field name, and should not be changed. Once you enter the Field Name and Operator, some of our internal CRM Rules! fire, and the form may display a field appropriate for the field type, to capture the input. For some fields, only the operator is required. Visionary Software, Company Confidential, All Rights Reserved, Oct 2012 v Page 19 of 59

20 For example, for Boolean (checkbox) fields, there are only two operators: checked and not checked. For date fields, you can either use just an operator to see if any date exists. If you use On, After, or Before, you will specify a Date in the date field provided. Visionary Software, Company Confidential, All Rights Reserved, Oct 2012 v Page 20 of 59

21 For integer fields, you have 6 operators that require a value, and allow you to do all of the basic integer comparison operations: =, <>, <, >, <=. >=. For Lookup and Option Set fields, you can see if they contain data or not, or are equal or are not equal to a specific lookup/option set value. The value field is a filtered lookup that only shows valid options for that field. Notice that for Option Sets you have defined in CRM, we translate them into lookups. Each option is stored as one record in the Entity Field Values table. Then, we create filtered lookups against that table so we can show you the friendly name of the options as you make your selection. We then translate those selections back into the number that is stored in CRM, and build our condition. Visionary Software, Company Confidential, All Rights Reserved, Oct 2012 v Page 21 of 59

22 Rule Actions Each Rule can have more than one Action. Each Action identifies the entity, field, and other information that is required for that action. As one Rule (Rule Definition record) can have many Actions, and as each Action can be re-used across many rules, the Rule Action entity is the intersection of this many-to-many that identifies the actions to be invoked for this one rule. You can also specify the sequence number if the order of operations is important. Rule Action Field Name Action Sequence Number Internal Rule Number Rule Action Name Post Condition Parens Explanation Select or build one action. By selecting it here, you are linking that action to this rule. Said another way, a rule can have one or more actions, and you select one from this lookup field. An optional field that will determine the order in which your actions are applied. The grid of Rule Actions displayed on the Rule Definition form is sorted by this number, for easier visibility into the sequence of your actions. An optional, FYI only, field. Often, specs have rules defined by number, so that you can more easily discuss them, or report bugs, etc. Rule numbers are defined as a quick search field, so using rule numbers enables you to quickly search and find a specific action. This displays on the grid, but is for informational purposes only. We have built code behind that form that will automatically derive this name field based on the action and sequence number If you use parenthesis in the pre-condition value field to create complex conditions, close the parenthesis using this field. Visionary Software, Company Confidential, All Rights Reserved, Oct 2012 v Page 22 of 59

23 Actions Each Action makes one change to your current CRM form. These Actions can be undertaken when the form is loaded or saved or when a field value changes. Note that when building a rule you do not need to specify a condition (often, for onload rules, the loading of the form is essentially the condition), but you must always specify at least one THEN Action for each rule. When you install our system, we automatically generate the following actions: - Hide Section - Show Section - Hide Tab - Show Tab You can re-use an action across many rules, so you only need to build each action once. The Action form appears as below when you add a new Action. Action Field Name Action Type Entity Name Owner Explanation See below; this is the key component of an action. When you select an Action Type, the form will change to show only the fields you need to fill in for us to generate the code to carry out that action type. Each Action must be linked to one CRM entity. This field drives filtered lookups, so that you, for example, only need to choose fields from this entity. The Name is prefilled (for most action types) to promote consistency in naming so that you can easily re-use rules. You can change this at any time, but if you change the rule components again, our rules will kick in and re-set the Name field value. You could decide to set up CRM Security so that users can only modify the rules they own. Each Action Type has different requirements. If you want to hide a field, all we need to know is the entity and field name. If you want to show a section, then we need to know the entity and Form, Tab and Section. Interestingly, our CRM Rules! action form uses CRM rules! to hide and show the fields we need to capture values in to write the code to invoke that action. Visionary Software, Company Confidential, All Rights Reserved, Oct 2012 v Page 23 of 59

24 Rule Action Types The key to understanding CRM Rules! are the Rule Action Types: these define the actions that you can take in response to conditions. Our goal is to continuously expand the Rule Action Types available, until we support all JavaScript functions outlined in the CRM SDK. We plan to prioritize new rule action type development based on customer request, and hope to release a new CRM Rules! version each month, to continually provide added value for your maintenance or subscription dollars. This table summarizes the 26 Rule Action Types currently available in CRM Rules! v2.0. The second column identifies the CRM Rules! version you need to purchase to gain availability to this rule. Following this overview, we divide the rules into different categories based on expected usage. # Version Rule Action Type Name Brief Description 1 Pro Always Submit Field Submits the field when the record is saved. 2 Pro Custom JavaScript Enter custom JavaScript 3 Std Disable Field Make a field not available for input (grayed out) 4 Std Enable Field Enable a field for input. 5 Pro Display Message Display an alert and stop the save, or a warning msg. 6 Std Format Phone Number Format Phone Number: = Std Hide Field Hide a field from the now visible form 8 Std Hide Section Hide a section 9 Std Hide Tab Hide a tab 10 Std Required Fields Set a field to be required, recommended, or none. 11 Pro RUN RULE! Run another CRM Rules (so you can nest) 12 Pro Run Workflow Run a CRM workflow 13 Pro Set Field to Derived String Set a field to any number of fields and text values Concatenation value 14 Pro Set Field to Other Field Value Set a field to the value of another field on the same entity. 15 Pro Set Field to Value From Other Set a field to the value of a field on a related entity Entity 16 Pro Set Field Value Set a field value to a constant value 17 Pro Set Option Set List Define which values appear in an option set. 18 Std Show Field Show a field 19 Std Show Section Show a section 20 Std Show Tab Show a Tab 21 Std Collapse Tab Make the tab one line 22 Pro Fire OnChange Technical: when you set a value, run that fields onchange event 23 Std Expand Tab Expand the tab from one line to a full tab 24 Pro Set Focus Move the cursor to a specified field for input 25 Pro Set to Null Clear out a field; set it to blanks; or nulls. 26 Pro Set Field To Mathematical Function Can add, subtract, multiply and divide field values 27 Pro Copy Field<s) From Lookup Entity Copy one or more fields from an entity (in one call) 28 Std Disable All Fields Disable all fields on a form 29 Std Enable All Fields Enable all fields on a form. 30 Pro Set Field to Now Set a date field to the current date and time 31 Pro Invoke Process Dialog Begin a process dialog Visionary Software, Company Confidential, All Rights Reserved, Oct 2012 v Page 24 of 59

25 Action Type Categories The current list of action types can be divided into the following categories: Action Category Visual Set Value Process Technical Description Change the appearance of a form Set the value of a field Set required fields, available option sets, Count Children, etc. For more technical developers, these rules offer additional control over the processing flow The visual actions are all available in the Standard version, while the rest are available in the Professional version. We have new features in development that will be available only in the Enterprise version. Visual Actions Explained: Hide/Show Fields, Sections, Tab These Action Types enable administrators to simplify forms by hiding Tabs, Sections, and Fields from view, typically done onload of the form. You then build data driven rules to make the Tab, Section, or Field display when it is relevant. Expand/Collapse Tab can make a tab collapsed or expanded, if your specified conditions are true. The Set Focus command then allows you to direct input to a specific field, useful when there are data errors. Disable Field makes the text in it gray, and nobody can make any changes to it. Enable Field makes the field available for input. Disable All Fields will essentially lock a form; it is typically used in conjunction with one or two Enable Field actions following the Disabling of all fields, to quickly disable all but a few fields. Enable All Fields allows you to open everything, most often used as an ELSE Action to one that disables all fields. Visionary Software, Company Confidential, All Rights Reserved, Oct 2012 v Page 25 of 59

26 # Rule Action Description/Usage Type Name 3 Disable Field No longer allows input into this field. Useful to show derived field. Note: you can do this through the CRM interface by checking Read Only. If you want it disabled most of the time, check this box and create Enable Field rules for the exceptions. 4 Enable Field Allows data input into this field. Opposite of Disable Field. Useful to only allow data to be entered under specific circumstances. 7 Hide Field Removes the field from view. Same effect as UNchecking the Visible by default box on the Field Properties. 8 Hide Section Removes the section from view. Again, can do this in the form, which avoids a screen flash. But, after you show the section, another rule may hide it again. 9 Hide Tab Removes the tab from view. 18 Show Field Shows the field, after it has been hidden. (To always show it, or to show it when the form loads, check the Visible by default box on Field Properties.) 19 Show Section Shows the section, after it has been hidden. 20 Show Tab Shows the tab, after it has been hidden. 21 Collapse Tab Makes the selected tab collapsed. Could use this to shrink the form length on load. Opposite of Expand Tab. 23 Expand Tab Expands the tab. Same as if user clicked the arrow next to a tab. Opposite of Collapse tab. Note: Can set the tab s property in CRM; if it should usually be open, set it there. 28 Disable All Will set all fields on the form to read-only mode. Fields 29 Enable All Fields Will set all fields on the form to accept input. Each Field, Section and Tab has a property box in CRM. (Open any form, and double-click any field, section or tab to view.) Show has the same effect as checking this visibility box. Hide has the same effect as UNchecking this Visible box. Visionary Software, Company Confidential, All Rights Reserved, Oct 2012 v Page 26 of 59

27 Set Value Actions Explained: Set Field Value These Action Types enable administrators to dynamically set the value of fields on the current form. Format Phone Number changes the data stored in the database to include dashes, e.g.. You can concatenate strings together, and assign the result to a field on the form. # Rule Action Type Name Description/Usage 6 Format Phone Number Format Phone Number: = Set Field to Derived String Concatenation value Set a field to any number of fields and text values. Very useful for setting Name fields to a derived value. 14 Set Field to Other Field Value Set a field to the value of another field on the same entity. Useful if you want users to select lookups, or enter custom text. This enables you to set the text field to the lookup value. Then, you can use the text value on views to show custom and lookup values in one column. 15 Set Field to Value From Other Entity Set a field to the value of a field on a related entity. Mapping only works for the Create of a record. This can sync values in a child entity after they have changed in the parent entity. 16 Set Field Value Set a field value to a constant value. Based on the field type, CRM Rules! shows a field of the proper type to store the value. 25 Set to Null Clear out a field; set it to blanks; or nulls. 26 Set Field To Mathematical Function Can add, subtract, multiply and divide field values. 27 Copy Field<s) From Lookup Entity You can traverse any lookup on any form, and bring in values from that parental (lookup) entity onto the current form. 30 Set Field to Now Set the value of a date field to the current date and time Visionary Software, Company Confidential, All Rights Reserved, Oct 2012 v Page 27 of 59

28 Process Actions Explained These Action Types enable administrators to modify the flow of the CRM form, and initiate other actions. # Rule Action Type Brief Description Name 5 Display Message Display an alert and stop the save, or display a warning message and allow the save. 10 Required Fields Set a field to be required, recommended, or none. This is a powerful way to improve the quality of your data, as you can easily write rules to require more fields based on the fields already filled in. (Note: this is for conditionally required fields; if a field is ALWAYS required, you can set it using the field properties in native CRM.) 11 RUN RULE! Run another CRM Rules (so you can nest rules). This enables you to generate rules of any complexity, and also can simplify your code libraries, and the efficiency of your code. For example, if you have a number of rules to fire if 3 conditions are true, you can write one rule with those three conditions, and then add Run Rule actions to apply additional conditions and actions. 12 Run Workflow Run a CRM workflow. You can write a CRM workflow and indicate it should fire on save, and you check the boxes indicating which fields, if changed, will fire the workflow. Well, if any of those fields are changed, this workflow will run. If the workflow conditions are not met, then the workflow doesn t really do anything; but you have a record in the Workflow item on the form. Instead, you can use CRM Rules! to write those conditions, and indicate the workflow to run. Now, that workflow will only fire WHEN the conditions that cause the workflow to actually do something are met. Users can then see workflows that actually modified data in the left nav bar. 17 Set Option Set List Define which values appear in an option set. If you have 20 values in an option set, you may not always want all of them to appear. Using this rule, you can identify which of the options are available, when the conditions you specify are met. This enables you to create hierarchical option sets; or option sets that depend on the value of another option set (or any other field). 24 Set Focus Move the cursor to a specified field for input. Very useful when paired with rules that validate data. If your conditions aren t met, use the display message action to tell the user what is wrong, then set focus to that field. 31 Invoke Process Dialog OOB, users must click a button to invoke a workflow. Now, you can invoke one based on the data values of any field on a form. Visionary Software, Company Confidential, All Rights Reserved, Oct 2012 v Page 28 of 59

29 Technical Actions Explained These Action Types are more esoteric, and our used to exert greater control over how CRM behaves. While they are more technical in nature, knowing how these rule types work, and when to apply them, can be critical to your rule behaving as expected in all situations. For example, one of our most common support calls is when developers build a rule to update a readonly field, but then don t force submit. So, if you see the value appear on the form, in a read-only field, but when you refresh that form, it doesn t show the new value, you need to add the Always submit action just after you set that field value. # Rule Action Type Description/Usage Name 1 Always Submit Field If you set a field value of a field that is disabled, that change won t be sent to the CRM Save event. To fix this, create a rule that always submits that field to the CRM Save event, and your change will be preserved in the DB. 2 Custom JavaScript If you already have JavaScript on your forms, but want to integrate all rules within the CRM framework, you could move all existing code into one Custom JavaScript rule. In this way, you ll be able to add new rules, and integrate them with the event handlers that run your custom script. It can be a good starting point for getting all of your rules into CRM; move all code into custom JavaScript rules, and you could then later re-write individual rules as CRM Rules! as time permits. 22 Fire OnChange This will cause the specified field s onchange event to fire. If you set a field value in an action, then you should set this fire on change checkbox on the action, if you want the onchange events for that field to fire. Visionary Software, Company Confidential, All Rights Reserved, Oct 2012 v Page 29 of 59

30 Chapter 3: Individual Action Types Explained In this section, we give you details behind the individual CRM Rule Action Types, and what you need to enter to make them work properly. Note that all actions need an action type and an entity. The following section defines what else you need to specify to make a rule work. These are arranged by order of how much you need to specify to make these rules work, the rules that require the least additional info are discussed first. Enable All Fields, Disable All Fields We only need to know what entity and form you are disabling (or enabling) all fields for. The form will be specified in the Event Handler section, so all we need on the action is the entity. Hide Field, Show Field, Enable Field, and Disable Field These rule types hide or show or disable or enable one field. All we need to know is the Field Name. When you enter the Field Name, we will identify the Field Type, even though that information is not required to carry out these action types. Set Focus If you want to give one field the focus (define on what field the cursor is to be placed), you simply need to give us the field name. Typically, this is used in an onload event, so when a form is displayed, the field you want gets the focus. (Note: the existing CRM bug, that does not allow the focus to be set to a lookup field if it is the first field on the form, still applies here. In other words, we don t solve that bug. In this case, the field will have focus, but you can t click into it.) Visionary Software, Company Confidential, All Rights Reserved, Oct 2012 v Page 30 of 59

31 Fire On Change If you update a field manually in CRM, the CRM engine will automatically run all of the event handlers you have tied to this field s onchange Event. If you update a field through code (a/k/a a CRM Rule action), and you have onchange code attached to the field you update, then you often want to add this action, so that all of the actions linked to the updated field s onchange event will fire. For example, if you update the Contact Type, then you may want to run the code that would run when a user updated the Contact Type. To achieve that, just add this Fire On Change action, specifying the same field that a previous rule updated. Always Submit Field Similarly, when you select the Always Submit Field action, all we need to know is the field name. This action will be required if you create an action that updates a read-only, or disabled, field, AND you want that updated value to be stored in the database for that record. If you don t add this action, then the update will take place, but will only be valid while that form is open. When the form is closed, that update would be lost. Field Evaluation This (poorly named) action will allow you to specify an alert message, and indicate if the save operation should be rolled back. This is most commonly used for Data Validation. You specify the conditions that are invalid in the Rule Conditions part of the Rule Definition form. Then, you add a Field Evaluation message that will display an alert message to the user whenever those conditions are true. If you set Allow Record Save to No, then this update will not be allowed to continue. The form contents are not saved. This is similar to an Error Message. Visionary Software, Company Confidential, All Rights Reserved, Oct 2012 v Page 31 of 59

32 If you set Allow Record Save to Yes, then the update will be allowed to continue. This equates to a Warning Message. Invoke Process Dialog You first need to build the process dialog using the OOB CRM Settings / Processes dialog. Then, you can invoke that dialog in response to any form event! You can also ensure that a record is saved (data on an unsaved form is not available to a process dialog), or save it after the dialog runs, by checking the appropriate boxes. Run Workflow You first need to create the workflow using the OOB CRM Settings / Processes dialog. Then, you can run it in response to any form event. Visionary Software, Company Confidential, All Rights Reserved, Oct 2012 v Page 32 of 59

33 Run Rule! You can nest CRM Rules! rules. This will duplicate a nested IF type of programmatic structure: IF <conditions true> THEN <run rule> IF <conditions true> THEN <take action> To create this type of rule, just enter the entity, which you give you a filtered list of the rules you have built attached to this entity. (Note: you can only run rules in the same entity that you are writing this rule for.) Run rule can be used to save you a great deal of time. Let s assume you have a dozen rules that only apply when the Case status is In Progress, and the Case Type is Bug. They all may have an additional condition, but they share those two conditions. You can write one rule that has those two conditions, and then use the Run Rule action to call another rule that perhaps has a condition of Priority = High, and another Run Rule Action to call another rule that has a condition of Priority = Medium. Note that there is an Event Handler selection of Run Rule. This reminds you that you don t need to deploy a rule, as another rule will call it. This is similar to a child workflow: you don t allow the user to select it directly, but it is called by another process. So, with CRM Rules!, you would place the event handler on the rule that CALLS the Run Rule actions, NOT on the rules that are called. Visionary Software, Company Confidential, All Rights Reserved, Oct 2012 v Page 33 of 59

34 Format Phone Number Currently, we offer two ways to format a US Phone Number. We hope to add support for regex expressions in early 2013 that will enable international users to format their phone numbers. For now, the option set provides you with two options, shown below. Just specify the field name, pick the format, and you re done! Visionary Software, Company Confidential, All Rights Reserved, Oct 2012 v Page 34 of 59

35 Expand Tab, Collapse Tab, Show Tab, Hide Tab When performing actions that affect a tab s appearance, all we need to know is the form and tab name. The Rule Target Form is a filtered lookup, based on the Entity entered, so it will only show you forms for this entity. (If you only have one form per entity, just type the letter I in this field, and hit tab, and the default Information form will be selected.) The Tab is a filtered lookup, based on the form selected. Hide Section, Show Section When hiding or showing the section, all we need to know is the Form, Tab, and Section name. The Form and Tab are the same filtered lookups as used for Tab actions; now, you must add the section within a form and tab that you want to hide or show. The Rule Target Section field is also a filtered lookup based on the Tab selected. Visionary Software, Company Confidential, All Rights Reserved, Oct 2012 v Page 35 of 59

36 Required Fields You can set a field to required, recommended, or none, just like you can on a CRM Field Attribute page. But now, you can conditionally set a field to required (or not) based on data and events. All we need to know is the field name, and if you want to set it to be required, or not. Note that this action will display the red asterisk to indicate that a field is required, and therefore uses the OOB CRM alert <Field Name> Required. That means that the required field will only be enforced onsave. If you wanted to give them an alert at the same time you made the field required, you would need to use the Field Evaluation method to display the alert. Programming Design Note: if you create a condition and set a field to be required in the THEN action section, you should typically set it to be NOT required in the ELSE action section. The only time when this shouldn t apply is if you have many rules that set a field to be required. But even then, I d suggest finding a way to combine the conditions so that you have one and only one rule to set one field required. Otherwise, you run the risk of two competing rules that set it to be required, then another that might set it back to not required. Visionary Software, Company Confidential, All Rights Reserved, Oct 2012 v Page 36 of 59

37 Custom JScript You can create a custom JScript Rule Type, which means that the entire rule is custom code. But you can also create a standard IF/THEN rule that has as one of its actions, your piece of custom code. To add this action, just paste in the code in the box provided. Important Note! As CRM Rules! automatically surrounds custom code with a function name and the flower box at the top of every rule, this code block should NOT include the function name. This means that you cannot pass parameters to a custom JScript action. If you have a function that requires parameters to be passed to it, that must be created as a standalone Custom JScript rule type. Set Option Set List First, build a CRM option set, either a global one or not, that contains all of the possible selectable values. Then, if you only want some options available, you can set a rule to do that. To build this action, all you need to specify is the field name. Visionary Software, Company Confidential, All Rights Reserved, Oct 2012 v Page 37 of 59

38 Then, SAVE this action record. (Notice the grid reminds you.) OnSave, our system will look into our Entity Field Value table and create one Option Set record for each value available in that option set, and refresh the grid. You then simply need to select the options you do NOT want to be visible, click the Edit button, and uncheck the VisibleYN box. When you click save, the grid will show the options that will be visible first, followed by those that will not be visible. Visionary Software, Company Confidential, All Rights Reserved, Oct 2012 v Page 38 of 59

39 When this rule runs, only the Bill To, Ship To, and Primary options will be displayed. Note that this Action Type enables you to create dependent picklists (a/k/a Hierarchical picklists or hierarchical option sets, or dependent option sets). To do this, you need to create one rule for each option in the first option set, each with an action that sets the applicable values in the second, dependent, option set. Visionary Software, Company Confidential, All Rights Reserved, Oct 2012 v Page 39 of 59

40 Set Field Value Action Types We have a number of Action Types that allow you to set a field value. All of them of course require that you specify which field is to be updated. Each then require different information to carry out the action, and display different fields, to capture input for the appropriate field type. The ways in which you can set a field value include: Set Field Value Type Set Field Value Set Field to Derived String Concatenation value Set Field to Other Field Value Set Field to Value From Other Entity Set to Null Set Field To Mathematical Function Copy Field<s) From Lookup Entity Set Field to Now Explanation Set a field value to a constant value Set a field to any number of fields and text values, linked together. (e.g., Set the Opportunity Name to: <Company>: <Probability>: <Est Close Date>: <Expected Value>) Set a field to the value of another field on the same entity. Set a field to the value of a field on a related entity Clear out a field; set it to blanks; or nulls. Can add, subtract, multiply and divide field values Copy one or more fields from an entity (in one call) Set a date field to the current date and time There are also two new Rule Types that can set field values: Count Children, and Sum Fields Across Children. Set Field to Now This will set a date field to the current date and time. Fire On Change Note that you can elect to Fire On Change after setting this field value. This appears regardless of the field type. Best practice is to Fire On Change; if there are no events attached to that field, CRM will gracefully exit; if there are, they will run. Perhaps more importantly if you later add an event to that other field, you don t have to later come back to this rule and remember to set fire on change then. Visionary Software, Company Confidential, All Rights Reserved, Oct 2012 v Page 40 of 59

41 Set Field to Null This action will blank any field. You just need to specify the field name. Set Field to Mathematically Derived Value This action lets you add, subtract, multiple, and divide fields and other fields, and/or constants. You can do things like: C=A+B, C=A+2, C=A-B, C=A-2, C=A/B, C=A/100, C=A*B, C=A*100 In addition, Parenthesis enable you to combine these operators in any way, e.g. C = (((A+B)/100)*(((A-B)*45))/100))/100. Visionary Software, Company Confidential, All Rights Reserved, Oct 2012 v Page 41 of 59

42 Example Equation To set up an equation, you build it line by line. Let s assume we take the standard estimated revenue equation and add a 90% fudge factor.. My Revenue = Probability * Expected Amount * 90 / 100 To create a rule that will perform this calculation: 1) Select the *math Action Type (you can enter *math into the Rule Type to select it) 2) Enter the entity, and select the field name you want to store the calculation in. In the example shown above, My Revenue was selected as the target field. (A custom field added to the Opportunity entity). Save it. 3) Click into the grid area to enable the toolbar so you can click Add New Rule Math. 4) On the New Rule Math form, you can add, subtract, multiply, or divide two fields, or one field and one constant. In the example above (I m going to say via the Transitive Property?), I can rewrite it to be Expected Amount * 90 * Probability / 100. The end result will look like this: Set Field to Derived String Concatenation value I know, that s a long action type name What you can do with this is combine field values and other text strings to derive a field s value. The best example is that companies often want to set the opportunity topic field to a concatenation of fields, to give sales reps a quick view of the Opportunity in one field. For example: Set the Opportunity Topic to: <Account>: <Probability>: <Est Close Date>: <Expected Value>) We can build a rule that combines the name of the Account linked to the opportunity, add a colon and a space between that and the Probability field, then add the Estimated Close Date field value, and the Expected Value field value. Visionary Software, Company Confidential, All Rights Reserved, Oct 2012 v Page 42 of 59

43 To set up this rule: 1) Select the Set Field to Derived String Concatenation Value action type. 2) Select the Entity (in this example, Opportunity) 3) Select the Field (in this example, Topic) 4) And Save the action (not save and close, we re not done ) 5) Now that we have saved our Action header, we can get to work building the string. To start, move the cursor into the grid, and click the Add New Rule Derivation button. 6) On this form, enter the sequence number. The string will be built in sequence number order, left to right. So, the first thing we want to do is show the name of the Account this Opportunity is linked to, so we select that field name in the Field name box. I also want to append a colon and a space after the name, so I click the String After Field lookup. Visionary Software, Company Confidential, All Rights Reserved, Oct 2012 v Page 43 of 59

44 7) The String After Field and String Before Field each let you build the text portions of your derived strings. In this case, we re going to add a colon, and check the space after text box, so we add a space. (This adds : to the text string.) 8) OK, we ve finished our first part, but it will get easier 9) We now want to add the Probability field value, and another colon and a space. Click Add New Rule Value again. Visionary Software, Company Confidential, All Rights Reserved, Oct 2012 v Page 44 of 59

45 10) This time, we add 1 to the sequence number (you can add 10, or 100 if you like, to leave room in case you change your mind, or the requirement changes not that that ever happens ). 11) We also select the Probability field, and as we want the same colon / space combination, I can just select that string. 12) Save and Close that, and our grid now looks like this: 13) Now, repeat: click the Add New Rule Derivation button, enter sequence number 3, and add the Estimated Close Date, and select the colon/space in the String After Field. 14) Repeat, adding sequence number 4 and the Estimated Value fields. (As this is the end of the string, do NOT select the colon/space value.) 15) Your grid should look like this: When you Validate this rule (to generate the code), you ll see the code is combing these values. When to Run Rules You can run this (and any) rule one of three ways: onload, onchange, or onsave. It may make sense to run this derivation rule one way over another, depending on how you (and your sales guys) operate. Typically, you d run this on the OnChange events of the components fields (Account Name, Probability, Est Close Date and Est Revenue), if you want to make it update immediately (and/or if users typically modify it after you prefill it). The end result: if any of those fields are changed, the Topic will be immediately updated, and will always be set to the same, standardized, components. The other possibilities and impacts are described in the table below. Visionary Software, Company Confidential, All Rights Reserved, Oct 2012 v Page 45 of 59

46 When to run rules: Event Effect When to use Caveat OnLoad Refreshes the field value upon loading. Typically, not a good idea. If you only run this onload, it won t show the effects of your most recent update. And if you run it onsave, so it s stored, then why bother running OnSave onchange of each component field OnChange AND OnSave Will update the Field just before sending the data to the database. Will update the field each time any of the component parts change. Update the field each time any part changes, and when record saved. Rarely. If you only want to run this calculation once, and not immediately show the effects of the changes in the UI. Most immediate feedback to the user. Also enables them to change it after they enter the component parts (so that it becomes a prefilled value, not a derived and nonmodifiable value. If you want to ensure the value is always equal to the formula. In other words, user cannot overwrite this derivation. it again onload? Don t set the name field to required, as CRM will catch that it is blank before your onsave rule runs. One reason you may not be able to use this approach is if you have a divisor that isn t the first field you fill in, so you could get divide by 0 errors. Users aren t typically a fan when they can t overwrite something, but if you have another field for them, this can work. Set Field Value (to a constant) You can see the power of CRM Rules! at work when you use the Set Field Value rule, as we have many rules that run, and, based on the field type, display a different field, so you can enter the field value as you would expec. This is used by the Set Field Value rule to show: - An integer field for any numeric data type - A date selector for a date field - A text field to a text data type - A lookup field when the field type is either lookup or option set (we gather all of your option set data into our Entity Field Value table so we can have a filtered lookup based on field name to show you the valid values for your option set fields). Visionary Software, Company Confidential, All Rights Reserved, Oct 2012 v Page 46 of 59

47 In the screen example above, you can see that we selected a lookup field. The lookup field that appears is a filtered lookup that shows, in this case, the price lists. For checkboxes, you can uncheck it or check it. Visionary Software, Company Confidential, All Rights Reserved, Oct 2012 v Page 47 of 59

48 To set an integer or text field, you enter that value in the CRM Field Value field If we instead set the value of a date field, you see that the date control appears. Visionary Software, Company Confidential, All Rights Reserved, Oct 2012 v Page 48 of 59

49 Set Field to Other Field Value You can set one field to another field s value. In the lookup field, you select the field that contains the value you want to set the (Job Title, in this example) Field Name to. In other words, if your equation was: Set Job Title = Track Or, Set the Job Title equal to the Track field, the Field Name would be Job Title and you would select the Track field in the Set to this Field s Value field. Most often this is used if there are, e.g., three similar fields, and the user can only select one of them. You could then set another text field to the value of any of those three fields, whenever they changed. Then, you could just place this one field on views, and it would show the value from whichever of those three fields were filled in. Visionary Software, Company Confidential, All Rights Reserved, Oct 2012 v Page 49 of 59

50 Set Field Value to Field on Other Entity There are two ways you can set a field on an entity to a field from another entity. This Action Type does it for one field. The other action type is called Copy Field(s) From Lookup Entity. This action type was written first, then when users wanted to copy more than one field, we built the other action type, so that you only make one database call to retrieve that information. So, if you have more than one field to copy, you should use the other action type. Therefore, we just recommend you always use Copy Field(s) From Lookup Entity, instead of this action type. Visionary Software, Company Confidential, All Rights Reserved, Oct 2012 v Page 50 of 59

51 Copy Fields From Lookup Entity CRM Rules! latest enhancement is an Action Type we call Copy Field(s) from Lookup Entity, which will enable you to copy fields from the Account down to the Contact form, e.g., without coding. It will copy fields from the entity behind any lookup field onto your current form. For example, on the Opportunity Product field, you have a lookup to the Product entity. You can now copy any of the fields on the Product form to the Opportunity Product form, to show information about that product, or to use fields in calculations on that opportunity product form. And we make it really easy: just name the source and target fields the same, and we will automatically map them when you create the action. If they are named differently, you can quickly add that source/target mapping yourself, using the familiar CRM interface that underlies all of CRM Rules! To create this type of rule in CRM Rules!: a) Select the Action Type. b) Select the Entity you want to copy fields to. (Any entity in your CRM system that has a form) c) Select the name of the Lookup field that links back to the entity you want to copy data from. d) The Lookup Entity identifies the table that you want to copy data from. e) When you save the new action, CRM Rules! will search the entity and the lookup entity, and will automatically map fields that have the same name. Now, as you may only want to map custom fields with the same name, or not do this at all, you can select one of those three options here. (We also exclude things like createdon, etc. and you can alter that list on our custom entity we called Entity.) Visionary Software, Company Confidential, All Rights Reserved, Oct 2012 v Page 51 of 59

52 f) The mapped records can be deleted in bulk if you don t want some, or you can easily add new fields to sync up. To add new fields, just click on the subgrid and click Add New Copy Fields, and the following form will appear. Fields on the Copy Fields Form Sequence Getting Data Form This Entity Field Field Type Fire on Change Get Fields From Lookup Entity Field Force Submit Usage The Sequence number just orders the order in which the field values are copied. Prefilled with the entity you selected on the Action form (b above) The field you want to copy data into. (You have to first create a new custom (or use an existing) field to store this copied data. If the field doesn t appear, you need to click the Update Existing Fields button to refresh the metadata.) When you enter This Entity Field, we will figure out the field type, and display that Should be checked if you have any events running against This Entity Field, so they can respond to the (possible) change in value. The entity the lookup refers to, and is filled in from the Action form. The field that you want top copy data from. Should be checked if you want to force a read-only field to be updated in the database. Visionary Software, Company Confidential, All Rights Reserved, Oct 2012 v Page 52 of 59

53 Chapter 4: CRM Rules! Technical Architecture This section identifies the entities used in CRM Rules!, what they contain, and the intended usage for the data contained within these tables. Overview CRM Rules! is a managed solution that creates over 20 custom entities in the CRM System in which it is installed.. These tables are populated by our installation code, and by the metadata from your system, as detailed below. CRM Rules Entity Summary When you install our product, you need to first kick off our general setup process. This process is detailed in the appendix, and is also sent to you in the Quick Start Guide when you receive your solution and license key. Our CRM Rules solution contains the following entities. The content of these entities is detailed in the following sections, but is summarized directly below. We have grouped these entities by sub-areas for easier navigation. These tables present the entities in the order in which they appear in the left nav bar within the CRM Rules! area. Sub Area: Rule Management Most of your work will be done by clicking on the entries in this sub-area, and by opening record contained within them. CRM Rules Entity Rule Definitions Deployment History Entities CRM Rules! Setup Licensed Users General Purpose Each record contains all the information for one rule. An audit log of CRM Rules! operations such as Update Entity, Validation, and Deploying rules to CRM Each entity in your system (that contains at least one form) as one record in this entity. You open these records to click a button that captures the metadata for this entity from your CRM system. One record exists in this entity to capture system-wide settings. Each developer, or rule creator, needs to have an active record in this entity. Our license key, and your purchas amount, determines how many records can be active at one time. By default, you can activate one licensed user at a time. (More developer licenses can be purchased at a discount.) Note that our pricing does NOT vary based on the number of end users in your system. Visionary Software, Company Confidential, All Rights Reserved, Oct 2012 v Page 53 of 59

54 Sub Area: Rule Creation This area contains entities that are involved in the specification of a CRM Rule! You will typically not need to review the data at this level, but you can search these tables to search, for example, one condition, and find out what rules a condition is attached to. CRM Rules Entity Rule Conditions Conditions THEN Actions Actions ELSE Actions General Purpose Each rule can contain 0, 1 or many conditions. A rule can have many conditions, and each condition can be re-used across many rules,. This table is the intersection of this many-to-many relationship and contains one record for each condition linked to a rule. Each condition has one record in this entity. Each rule can contain 1 or many THEN actions. These actions are taken if the condition set within the rule evaluates to true. A rule can contain many actions, and actions can be re-used across rules, so this table is the intersection of this many-to-many relationship and conditions one record for each THEN action linked to a rule. Each action has one record in this entity. Note that both the THEN Actions and the ELSE actions re-use actions from this one entity. Each rule can contain 0 1 or many ELSE Actions. These actions are taken if the condition set within the rule evaluates to false. A rule can contain many actions, and actions can be re-used across rules, so this table is the intersection of this many-to-many relationship and conditions one record for each ELSE action linked to a rule. Sub Area: Rule Deployment This area contains the Rule Event Handlers, which indicate when each rule is to be run. You can, however, use these entities to find out what events are triggered when. You can also see this information for deployed rules within the OOB CRM Form Properties tab within a form. CRM Rules Entity Rule Events Rule Event Handler General Purpose Each form has one onload event and one onsave event, and each field can contain one onchange event. Typically, these records are created automatically by specifying the Rule Event Handlers in the Rule Definition form. Each rule can be triggered by one or more events. Each event can contain many event handlers (you can run more than one rule when the form loads, e.g.). Each rule can be triggered by one or more events. Therefore, this entity is the intersection table, and defines the events that will trigger each rule. Visionary Software, Company Confidential, All Rights Reserved, Oct 2012 v Page 54 of 59

55 Sub Area: Rule Details Some of our Rule Types and Action Types contain more than one record per rule. These values are stored in these tables. CRM Rules Entity Option Sets Rule Derivations Clone Details Rule Case Rule Math Copy Fields Rule Count Sum Rule Workflow Rule Process Dialogs General Purpose When you create an Option Set Rule Type, we populate this table with all of the possible values for the option set field identified in the Action. When you create a String Concatenation Action Type, the details of those actions are stored in this entity. When you specify a Clone Rule Type, the details behind the field mappings are contained here. When you use the CASE Rule Type, this table contains one record for each option set value for the field specified in the Rule Definition form. When you create a Mathematical Formula Action Type, the details are stored in this entity. When you use the Copy Field(s) from :Lookup Entity Action Type, each field that you copy will have one record in this entity. When you use the Count Children Rule Type, or the Sum Field(s) Across Child Entities Rule Type, the details of that operation are stored here. When you use the Run Workflow Action Type, this entity captures the information for the workflows invoked by each rule. When you use the Invoke Process Dialog Action Type, the details are captured in this entity. Sub Area: Rule Metadata The entities in this section contain the metadata from the CRM system into which CRM Rules! has been installed. Note that these entities can be very useful for finding rules attached to a certain field, for example. As CRM Rules! is a relational database, each rule that contains a condition for Field A can be seen by clicking on the Entity Fields nav bar item, opening the Field A record and looking at the Used in Conditions left nav bar entry within that record. CRM Rules Entity Entity Fields Entity Field Values Rule Target Forms Rule Target Tabs Rule Target Sections General Purpose Each field that can be used in a rule has one record in this entity. Again, you can use standard OOB CRM search function to find fields, and then you can open one record to see how that field is being used (or not) within CRM Rules. All option set value are stored here, as are (by default, the first 50) values from lookup fields. Another valuable entity to open, search, and review, to see what rules are using what fields. Each form in your system (for all entities for which you have clicked the Update Entity button) are stored here. If you want to know what rules are attached to a form, you can see that here (as well as in your OOB CRM Customization Form Properties tab.) Each Tab within a form has one record in this entity. Each Section (within a tab) within a form has one record in this entity. Visionary Software, Company Confidential, All Rights Reserved, Oct 2012 v Page 55 of 59

56 Sub Area: Rule Reference CRM Rules Entity General Purpose Rule Action Types Each Action Type has one record here. You typically don t need to review this data, but you can, for example, see all of the rules that Set Required Fields by clicking on that Action Type and reviewing the Rule Actions that use this Action Type. Operators When creating conditions, each field type allows you to enter certain operators. This entity simply contains one record for each possible operator, regardless of field type. Rule Types Each Rule Type has one record here. Again, you can then use this to find all rules that use the Count Children feature. Field Type Each Field Type (int, text, etc.) has many possible operators that can be used Operators in conditions. This entity contains that data. Field Types Each field has a field type. This short table identifies the fields types available today within CRM, and CRM Rules! Rule Strings When you create a String Derivation rule type, you can link together many NOTE! This really stringlets, or bits of text. You can re-use this rule strings across many rules, belongs under Rule so the base string is stored here. Details sub-area! Math Operators We currently support add, subtract, multiply and divide operators. As we expect to expand this list in the future, we created an entity to store the information we need to properly process each type, and to enable us to expand the types we support without code changes. Your CRM s Metadata Inside CRM Rules! When you install our product, we identify all of the entities in your system, and store them in our Entities table. To create rules for an entity, you need to open that entity record, and click the Update Entity Data button (s/s). When you click that button, we capture all of the metadata for that entity, and store them in the following custom entities (created when you install our CRM Rules! managed solution.) These tables are all empty until you click on the Update Entity button for the first entity. Note: You need to click the Update Entity button once for each entity that you want to build a rule on. CRM Object Stored in our custom Explanation CRM Rules! tables called Entity Entity Each entity (that contains a form) is stored in this table. Forms Rule Forms Each (non mobile) CRM form creates one record in this table. Tabs Rule Tabs (?) Each tab on each of the forms for this entity is stored here. Sections Rule Sections Each section, within each tab, is stored here Fields Entity Fields Each field on the entity creates one record in this table. Field Values Entity Field Values The values for each option set are stored in this table, as well as the (by default, first 50) records from a lookup entity. Visionary Software, Company Confidential, All Rights Reserved, Oct 2012 v Page 56 of 59

57 Refreshing Metadata When you add new fields to a CRM entity, or add or change option set values, or add sections or tabs to forms anything that you might want to write a rule for - to get them into CRM you have to click the Create/Update Entity Data button. This will create or refresh the form, tab, section, and field names, and field values from option sets and (the first 50) lookup field values. That will refresh the metadata for this entity. You can check the progress of this operation by clicking the Deployment History left nav bar. The default view for the Deployment History entity will show you the progress of this operation. So, when you make a change in the CRM Customization section, to make that appear in CRM Rules: 1) Click the OOB CRM button Publish All Customizations. 2) Click the Entities tab in the CRM Rules! Area 3) Double-Click to open the Entity to refresh, and 4) Click the Create/Update Entity Data button. 5) Check Deployment History for status. You may need to refresh a few times, or wait seconds for the operation to complete. You will see a number of status messages while you refresh and wait: Visionary Software, Company Confidential, All Rights Reserved, Oct 2012 v Page 57 of 59

58 You should see 7 lines in this grid, with the last one being the Conditions. When conditions shows a status of success, your new fields, etc. are now ready to be worked with in CRM Rules!. If your Lookup values don t refresh You probably have more than 50 of them. There are two things you can do: 1) If your lookup has More than 50 values, and less than a lot As people often use lookups instead of longer option sets, we wanted to be able to make it easy to create rules using those values as conditions. So, we bring in the first 50 records we find on the lookup entity. If you have more than 50, but less than 100 or so, you may want to increase the limit in the Settings entity. 2) If you have a lot of different values, build your own Entity Field Value lookup records! Key point: ALL of the option set and lookup field type lookups in CRM Rules! go against the Entity Field Values table. You can create new records in this table. If you want to create a specific rule for just one account, you could modify that number in step 1 above, but it might have to be a pretty big number to get all of the accounts in there. So, you can build your own Entity Field Value record, and it will be used just like any other option set or lookup value. Visionary Software, Company Confidential, All Rights Reserved, Oct 2012 v Page 58 of 59

59 The critical fields are of course the Entity, which you should enter first so you field the field names, the field name, in this example, the Account Name, and the Field Value. The Field Value is the name on the account that you want to create a rule for. (Note that hopefully there are better ways, like using an Account Number, but this is there in case you need it.) Visionary Software, Company Confidential, All Rights Reserved, Oct 2012 v Page 59 of 59