The Manipulation Library written by Carlton Colter

Extending Microsoft Dynamics® CRM Workflow

1 Overview............................................................................................................................................. 3

2 Installation.......................................................................................................................................... 4

2.1 Using the Solution......................................................................................................................... 4

2.2 Using the Plugin Registration Tool................................................................................................52.2.1 The Plugin Registration Tool....................................................................................................52.2.2 Workflow Registration..............................................................................................................5

3 Calculation utilities............................................................................................................................. 8

3.1 Basic Math..................................................................................................................................... 8

3.2 Convert Values.............................................................................................................................. 8

3.3 Maximum....................................................................................................................................... 9

3.4 Minimum........................................................................................................................................ 9

3.5 Solve Equation.............................................................................................................................. 93.5.1 Operators............................................................................................................................... 103.5.2 Constants............................................................................................................................... 113.5.3 Functions............................................................................................................................... 113.5.4 Capability............................................................................................................................... 12

4 Date Utilities...................................................................................................................................... 13

4.1 Add Business Days.....................................................................................................................13

4.2 Add Days..................................................................................................................................... 13

4.3 Parse Date.................................................................................................................................. 14

4.4 Subtract Business Days..............................................................................................................14

4.5 Subtract Days.............................................................................................................................. 15

5 String Utilities................................................................................................................................... 16

5.1 Capitalize..................................................................................................................................... 16

5.2 Codify (SoundEx)........................................................................................................................ 16

5.3 Codify (Metaphone).....................................................................................................................17

5.4 Length......................................................................................................................................... 17

5.5 Pad String.................................................................................................................................... 18

5.6 Replace....................................................................................................................................... 18

5.7 Substring..................................................................................................................................... 19

The Manipulation Library: A Workflow Library for Microsoft Dynamics CRM Page 1

5.8 Trim............................................................................................................................................. 19

6 RegEx Utilities.................................................................................................................................. 20

6.1 Format Matched String................................................................................................................20

6.2 Match........................................................................................................................................... 20

6.3 Replace....................................................................................................................................... 21

6.4 Return Match............................................................................................................................... 21

7 Web Utilities...................................................................................................................................... 22

7.1 URL Encode................................................................................................................................ 22

7.2 URL Decode................................................................................................................................ 22

8 Metaphone Duplicate Checking......................................................................................................23

8.1 Modifying the Account Entity.......................................................................................................23

8.2 Creating the Metaphone Workflow..............................................................................................23

8.3 Configuring Duplication Checking...............................................................................................24

The Manipulation Library: A Workflow Library for Microsoft Dynamics CRM Page 2

1 OVERVIEWAndrew Swerlick blogged about the Manipulation Library on Engage's Tech Blog and his words sum up the core of the Manipulation Library:

The 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.

Rewritten to work with CRM 2011 Beta, the Manipulation Library can now be used with Dialogs and Workflows.

The Manipulation Library: A Workflow Library for Microsoft Dynamics CRM Page 3

"Microsoft Dynamics CRM’s built in workflow engine is pretty powerful, as anyone who’s worked with it for a while is aware. However, in our experience, a good customer quickly comes up with requirements that go beyond it’s built in capabilities, requiring custom activities. Engage is used to writing some basic activities to handle common problems, but now thanks the Carlton Colter of Microsoft, there’s a robust library of basic workflow activities up on CodePlex for all CRM customers and partners."

2 INSTALLATION

2.1 Using the SolutionImport the Manipulation_Library_1_1.zip

1. Login to CRM as an Administrator2. Click Settings3. Click Solutions4. Click Import5. Follow the on-screen prompts to import Manipulation_Library_1_1.zip

The Manipulation Library: A Workflow Library for Microsoft Dynamics CRM Page 4

2.2 Using the Plugin Registration Tool

2.2.1 The Plugin Registration ToolThe CRM Plugin Registration Tool can be downloaded as part of the CRM 2011 SDK.

2.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.

3. Click Connect

The Manipulation Library: A Workflow Library for Microsoft Dynamics CRM Page 5

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 6

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 7

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 8

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 9

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 10

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 11

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 12

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 DaysThis 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 DaysThis 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 13

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 DaysThis 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 14

4.5 Subtract DaysThis 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 15

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 16

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 17

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 18

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 19

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 20

6.3 ReplaceReplace will use the regular expression to perform a text replacement.

Replace Input Parameters

Replace Output Parameters Invalid Regular Expression

o True if the Regular Expression pattern is invalid Result

o The resulting text after the pattern replacement.

6.4 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 21

7 WEB UTILITIES

7.1 URL EncodeURL encode the text.

URL Encode Input Parameters

URL Encode Output Parameters Result

o The URL encoded text.

7.2 URL DecodeURL decode the text.

URL Decode Input Parameters

URL Decode Output Parameters Result

o The URL decoded text.

The Manipulation Library: A Workflow Library for Microsoft Dynamics CRM Page 22

8 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.

8.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

8.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 23

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

8.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 24