The Manipulation Library
written by Carlton Colter
Extending Microsoft Dynamics® CRM Workflow
1
Overview ............................................................................................................................................... 3
2
Installation ............................................................................................................................................ 4
3
4
5
2.1
Using the Solution........................................................................................................................... 4
2.2
Using the Plugin Registration Tool ................................................................................................. 5
2.2.1
The Plugin Registration Tool ..................................................................................................... 5
2.2.2
Workflow Registration ............................................................................................................... 5
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................................................................................................................................ 9
3.5.1
Operators ................................................................................................................................ 10
3.5.2
Constants ................................................................................................................................ 11
3.5.3
Functions ................................................................................................................................. 11
3.5.4
Capability................................................................................................................................. 12
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
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
6
7
8
Trim ............................................................................................................................................... 19
RegEx Utilities .................................................................................................................................... 20
6.1
Format Matched String ................................................................................................................. 20
6.2
Match ............................................................................................................................................ 20
6.3
Replace ......................................................................................................................................... 21
6.4
Return Match ................................................................................................................................ 21
Web Utilities ....................................................................................................................................... 22
7.1
URL Encode ................................................................................................................................. 22
7.2
URL Decode ................................................................................................................................. 22
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
OVERVIEW
Andrew Swerlick blogged about the Manipulation Library on Engage's Tech Blog and his words sum up
the core of the Manipulation Library:
"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."
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
2
INSTALLATION
2.1
Using the Solution
Import the Manipulation_Library_1_1.zip
1.
2.
3.
4.
5.
Login to CRM as an Administrator
Click Settings
Click Solutions
Click Import
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
2.2.1
Using the Plugin Registration Tool
The Plugin Registration Tool
The CRM Plugin Registration Tool can be downloaded as part of the CRM 2011 SDK.
2.2.2
Workflow Registration
1. 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
8. Click the
button to browse and select the ManipulationLibrary.dll file.
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 UTILITIES
The Calculation Utilities allow for quick calculations and logic based on numerical values.
Basic Math
3.1
Basic 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
Convert Values
3.2
Convert 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
Maximum
3.3
Maximum takes two parameters and returns the highest value.
Maximum Input Properties
Maximum Output Properties

Result
o The highest number out of the two numbers.
Minimum
3.4
Minimum takes two parameters and returns the lowest value.
Minimum Input Properties
Minimum Output Properties

Result
o The lowest number out of the two numbers.
Solve Equation
3.5
The “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
Operators
The 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
sin
Sine
The Manipulation Library: A Workflow Library for Microsoft Dynamics CRM
Page 11
sqrt
Square Root
tan
Tangent
trunc
Remove anything after the decimal place.
3.5.4
Capability
The 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 UTILITIES
The 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.
Add Business Days
4.1
This 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.
Add Days
4.2
This 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
Parse Date
4.3
This 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
.
Subtract Business Days
4.4
This 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
Subtract Days
4.5
This 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 UTILITIES
The String Utilities provide basic string operations, while the regular expression utilities provide more
advanced features.
Capitalize
5.1
Capitalize 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.
Codify (SoundEx)
5.2
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
Codify (Metaphone)
5.3
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
Length
5.4
Return 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
Pad String
5.5
Pad 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
Replace
5.6
Replace 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
Substring
5.7
Get 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
Trim
5.8
Remove 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 UTILITIES
The RegEx (Regular Expression) Utilities provide the ability to manipulate and search text more freely,
but it is also more taxing than basic string operations.
Format Matched String
6.1
The 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
Match
6.2
This 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
Replace
6.3
Replace 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.
Return Match
6.4
Return 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 Encode
URL encode the text.
URL Encode Input Parameters
URL Encode Output Parameters

Result
o The URL encoded text.
URL Decode
7.2
URL 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 CHECKING
Below 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 Entity
1. 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 Workflow
1. 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 Checking
1. 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