the manipulation library - mmcrm.rummcrm.ru/.../manipulationlibrary.docx · web viewthe...
TRANSCRIPT
The Manipulation Library written by Carlton Colter
Extending Microsoft Dynamics® CRM Workflow
1 Overview............................................................................................................................................. 3
2 Installation.......................................................................................................................................... 3
2.1 The Plugin Registration Tool.........................................................................................................3
2.2 Workflow Registration................................................................................................................... 3
3 Calculation utilities............................................................................................................................. 6
3.1 Basic Math..................................................................................................................................... 6
3.2 Convert Values.............................................................................................................................. 6
3.3 Maximum....................................................................................................................................... 7
3.4 Minimum........................................................................................................................................ 7
3.5 Solve Equation.............................................................................................................................. 73.5.1 Operators................................................................................................................................. 83.5.2 Constants................................................................................................................................. 93.5.3 Functions................................................................................................................................. 93.5.4 Capability............................................................................................................................... 10
4 Date Utilities...................................................................................................................................... 11
4.1 Add Business Days to Date.........................................................................................................11
4.2 Add Days to Date........................................................................................................................ 11
4.3 Parse Date.................................................................................................................................. 12
4.4 Subtract Business Days from Date..............................................................................................12
4.5 Subtract Days from Date.............................................................................................................13
5 String Utilities................................................................................................................................... 14
5.1 Capitalize..................................................................................................................................... 14
5.2 Codify (SoundEx)........................................................................................................................ 14
5.3 Codify (Metaphone).....................................................................................................................15
5.4 Length......................................................................................................................................... 15
5.5 Pad String.................................................................................................................................... 16
5.6 Replace....................................................................................................................................... 16
5.7 Substring..................................................................................................................................... 17
5.8 Trim............................................................................................................................................. 17
The Manipulation Library: A Workflow Library for Microsoft Dynamics CRM Page 1
6 RegEx Utilities.................................................................................................................................. 18
6.1 Format Matched String................................................................................................................18
6.2 Match........................................................................................................................................... 18
6.3 Return Match............................................................................................................................... 19
7 Metaphone Duplicate Checking......................................................................................................21
7.1 Modifying the Account Entity.......................................................................................................21
7.2 Creating the Metaphone Workflow..............................................................................................21
7.3 Configuring Duplication Checking...............................................................................................22
The Manipulation Library: A Workflow Library for Microsoft Dynamics CRM Page 2
1 OVERVIEWThe Manipulation Library for CRM is a set of custom workflows for OnPremise Microsoft Dynamics® CRM to solve equations, manipulates strings, perform regex (regular expression) formatting and matching, as well as SoundEx and Metaphone-Like codification.
This software is provided "as is," without warranty of any kind, express or implied. In no event shall the author or contributors be held liable for any damages arising in any way from the use of this software.
If there are any problems with the Manipulation Library, please post it on CodePlex.
A special thanks to Engage Inc. for contributing Date Utilities to the Manipulation Library and doing a code review.
2 INSTALLATION
2.1 The Plugin Registration ToolThe CRM Plugin Registration Tool can be downloaded at: http://code.msdn.microsoft.com/crmplugin.
2.2 Workflow Registration1. Run the Plugin Registration Tool.
2. Connect to your CRM Server a. If you are running as an account that is a CRM Administrator you can leave the port,
domain, and username blank.
The Manipulation Library: A Workflow Library for Microsoft Dynamics CRM Page 3
3. Click Connect
4. Select the organization and click Connect.
5. Click the (Register) button on the toolbar.
6. Select Register New Assembly.
7. Click the button to browse and select the ManipulationLibrary.dll file.
8. Click the Register Selected Plugins button.
The Manipulation Library: A Workflow Library for Microsoft Dynamics CRM Page 4
9. Click Ok.
10. The Manipulation Library and its supporting workflow have now been registered; you can close the plugin registration tool.
The Manipulation Library: A Workflow Library for Microsoft Dynamics CRM Page 5
3 CALCULATION UTILITIESThe Calculation Utilities allow for quick calculations and logic based on numerical values.
3.1 Basic MathBasic math is very simple; it takes two numbers and a symbol. The symbol can be either plug (+), minus (-), divide (/), or multiply (*) symbol.
Basic Math Input Properties
Basic Math Output Properties Result
o The result of the mathematical operation
3.2 Convert ValuesConvert values takes in a string and returns a number in multiple formats.
Convert Values Input Properties
Convert Values Output Properties Decimal Float Formula Processing Error
o A boolean to let you know if there was an error converting the string to a number Money Rounded Number
o The number rounded to the nearest whole number Truncated Number
o The number truncated to a whole number
The Manipulation Library: A Workflow Library for Microsoft Dynamics CRM Page 6
3.3 MaximumMaximum takes two parameters and returns the highest value.
Maximum Input Properties
Maximum Output Properties Result
o The highest number out of the two numbers.
3.4 MinimumMinimum takes two parameters and returns the lowest value.
Minimum Input Properties
Minimum Output Properties Result
o The lowest number out of the two numbers.
3.5 Solve EquationThe “Solve Equation" workflow is an implementation of a .Net reverse polish notation. I used the pseudo code from Wikipedia to help write the convertor and postfix solver. The equation solver supports variables: @a, @b, @c, @d, @e, @f, @g, @h, @i, @x, @y, and @z. The formula can contain these variables as well as multiple constants and formulas.
Resources
It is important to note that reverse polish notation is not easy and required a lot of research to figure out the best way to get the implementation to work and be conscious of precedence. The resources listed below are some of the most helpful regarding reverse polish notation.
Wikipedia article on Reverse Polish Notation Wikipedia article on the Shunting Yard Algorithm for converting infix to postfix Dream-In-Code .Net Tutorial by Vincent Tam
The Manipulation Library: A Workflow Library for Microsoft Dynamics CRM Page 7
Solve Equation Input Properties
Solve Equation Output Properties Error Message
o The error message if there was an error processing the formula. Error Processing Formula
o Boolean (true if there was an error) Float Result Money Result Rounded Number Result String Result Truncated Number Result
3.5.1 OperatorsThe following operators are supported:
Operator Example Function
+ 1+2 Add: 1+2 = 3
- 3-4 Subtract: 3-4 = -1
* 1*2 Multiply: 1*2 = 2
/ 2/1 Divide: 2/1 = 2
% 20%6 Mod: 20 mod 6 = 2
^ 2^3 Power: 2 to the 3rd power = 8
The Manipulation Library: A Workflow Library for Microsoft Dynamics CRM Page 8
3.5.2 Constants
Constant Value
e 2.71828182845904523536
pi 3.14159265358979323846
rand A Random Number between 0 and 1
3.5.3 Functions
Function Description
abs Absolute Value
acos Arccosine
asin Arcsine
atan Arctangent
cos Cosine
degrees Convert radians to degrees
even Rounds up to the nearest even integer
fact Factorial – Example: fact(5) = 5 * 4 * 3 * 2 * 1
gcf Greatest Common Factor (Included as an example math function)
log log(number,base)
log10 Log Base 10 of a number
max Maximum Value – Can take multiple parameters
min Minimum Value – Can take multiple parameters
neg A negative number neg 1 = -1 THIS IS NEEDED FOR INTERNAL USE ONLY
odd Rounds up to the nearest odd integer
power power(a,b) = a^b
radians Convert degrees to radians
randbetween A random number between the two numbers passed – Example: randbetween(1,10)
round Rounds the number 1 to the number 2’s number of decimal places.
sign 1 if positive, 0 if 0, -1 if less than 0
The Manipulation Library: A Workflow Library for Microsoft Dynamics CRM Page 9
sin Sine
sqrt Square Root
tan Tangent
trunc Remove anything after the decimal place.
3.5.4 CapabilityThe Solve Equation workflow allows complex algorithms to be calculated and their results to be stored within objects in CRM. The source code is included to allow you to extend the functions available.
The Manipulation Library: A Workflow Library for Microsoft Dynamics CRM Page 10
4 DATE UTILITIESThe Date Utilities provide a way to manipulate dates. They are a starting point and could still use additional workflow activities like DateDiff. These functions were provided by Engage. A special thanks to them for contributing to the manipulation library.
4.1 Add Business Days to DateThis Workflow Activity allows Business Days to be added to a date. You can also just add the days directly to a date, and make sure the last day is a business day.
Add Business Days to Date Input Parameters
Add Business Days to Date Output Parameters Result
o The modified date.
4.2 Add Days to DateThis Workflow Activity allows Days to be added to a date.
Add Days to Date Input Parameters
Add Days to Date Output Parameters Result
o The modified date.
The Manipulation Library: A Workflow Library for Microsoft Dynamics CRM Page 11
4.3 Parse DateThis Workflow Activity allows parses a date.
Subtract Business Days to Date Input Parameters
Subtract Business Days to Date Output Parameters AM Day Day of Week Day of Week (Text) Day of Year Hour (12-Hour-Clock) Hour (24-Hour-Clock) Minute Month PM Week Number Year
.
4.4 Subtract Business Days from DateThis Workflow Activity allows Business Days to be subtracted from a date. You can also just subtract the days directly from a date, and make sure the last day is a business day.
Subtract Business Days to Date Input Parameters
Subtract Business Days to Date Output Parameters Result
o The modified date.
The Manipulation Library: A Workflow Library for Microsoft Dynamics CRM Page 12
4.5 Subtract Days from DateThis Workflow Activity allows Days to be subtracts from a date.
Subtract Days to Date Input Parameters
Subtract Days to Date Output Parameters Result
o The modified date.
The Manipulation Library: A Workflow Library for Microsoft Dynamics CRM Page 13
5 STRING UTILITIESThe String Utilities provide basic string operations, while the regular expression utilities provide more advanced features.
5.1 CapitalizeCapitalize either the first character or the first letter of every word in the string.
Capitalize Input Parameters
Capitalize Output Parameters Result
o The capitalized string.
5.2 Codify (SoundEx)Encode a string using SoundEx.Codify (SoundEx) Input Parameters
Codify (SoundEx) Output Parameters Result
o The SoundEx codified string
The Manipulation Library: A Workflow Library for Microsoft Dynamics CRM Page 14
5.3 Codify (Metaphone)Encode a string using an algorithm that is similar to Metaphone. Metaphone is a phonetic algorithm published in 1990 for indexing words by their English pronunciation. The original metaphone algorithm was developed by Lawrence Phillips who later created a double-metaphone algorithm to produce more accurate results. This algorithm is an implementation somewhere between metaphone and double-metaphone. It handles some of the special cases that are handled in double-metaphone, but still does a single codification. In this version, the metaphone codification is processed by funnelling through a translation table. If you would like to modify the translations, change the definitions in the static class Metaphone.cs.Codify (Metaphone) Input Parameters
Codify (Metaphone) Output Parameters Result
o The Metaphone codified string
5.4 LengthReturn the length of the string.
Length Input Parameters
Length Output Parameters Length
o The length of the string
The Manipulation Library: A Workflow Library for Microsoft Dynamics CRM Page 15
5.5 Pad StringPad the string with a specific character on the left or the right.
Pad String Input Parameters
Pad String Output Parameters Result
o The padded string
5.6 ReplaceReplace text within the string. It can be either case sensitive or case insensitive.
Replace Input Parameters
Replace Output Parameters Result
o The string with the text replaced
The Manipulation Library: A Workflow Library for Microsoft Dynamics CRM Page 16
5.7 SubstringGet a particular section of a string either starting with the beginning or the end as the point of reference.
Substring Input Parameters
Substring Output Parameters Result
o The substring
5.8 TrimRemove the spaces surrounding a string.
Trim Input Parameters
Trim Output Parameters Result
o The trimmed string
The Manipulation Library: A Workflow Library for Microsoft Dynamics CRM Page 17
6 REGEX UTILITIESThe RegEx (Regular Expression) Utilities provide the ability to manipulate and search text more freely, but it is also more taxing than basic string operations.
6.1 Format Matched StringThe Format Matched String utilizes RegEx.Replace to allow the formatting of strings. The default parameters will format a telephone number for US numbers.
To implement this and allow extension, it is ideal to parse the extension separately, then if there is an extension, append an x and the extension to the number.
Format Matched String Input Parameters
Format Matched String Output Parameters Result
o The formatted string Invalid Regular Expression
o True if the Regular Expression pattern is invalid Match Found
o True if a match was found
6.2 MatchThis matches a regular expression
Match Input Parameters
Match Output Parameters Invalid Regular Expression
o True if the Regular Expression pattern is invalid Match Found
o True if a match was found
The Manipulation Library: A Workflow Library for Microsoft Dynamics CRM Page 18
6.3 Return MatchReturn Match will return a specific match using the index provided or all matches joined together.
Return Match Input Parameters
Return Match Output Parameters Invalid Regular Expression
o True if the Regular Expression pattern is invalid Match Found
o True if a match was found Match
o The text that matched
The Manipulation Library: A Workflow Library for Microsoft Dynamics CRM Page 19
The Manipulation Library: A Workflow Library for Microsoft Dynamics CRM Page 20
7 METAPHONE DUPLICATE CHECKINGBelow is an example of how to use the metaphone codification for duplicate name checking on an account. SoundEx can be used for duplicate name checking too.
7.1 Modifying the Account Entity1. Click Settings in the left navigation
2. Click Customization, then Customize Entities
3. Double-click Account
4. Click Attributes on the left navigation
5. Click New
6. Add a new attribute to the account called Metaphone. It does not need to be searchable.
7. Click Save and Close
8. Click Save, then Click Actions, Publish
7.2 Creating the Metaphone Workflow1. Create a new workflow called Account Metaphone Codification
2. Check the box for Record attributes change
The Manipulation Library: A Workflow Library for Microsoft Dynamics CRM Page 21
3. Click Select, Check the box for the Account Name, and click Ok
4. Add the Codify (Metaphone) Workflow Step and configure it as follows:
5. Add an Account Update Step, and put the Codify Result into the Metaphone Field (which should be on the Additional Fields Tab)
6. Save and Publish the Workflow
7.3 Configuring Duplication Checking1. Click Settings in the left navigation
2. Click Data Management, then Duplication Detection Rules
3. Click New
4. Setup a Duplicate Check like the following:
The Manipulation Library: A Workflow Library for Microsoft Dynamics CRM Page 22