Here at docMgt we spend a lot of time talking to our users about ways to make our products better. One common request we get is to make it easier to find things. Not just once, but on a consistent basis. Another is to make it easier to compute due dates and other significant trigger dates. When we get these requests I feel like I am turning into my parents when I say “don’t forget to eat your variables
vegetables.” That probably sounds like just a silly joke but there is a lot of truth to it. One thing we take great pride in is the variable replacement technology available in docMgt.
What is a variable? A variable is merely some coded text that refers to other values. When docMgt sees a variable it will replace that variable with the value(s) that the variable refers to. For instance, the variable [DATE] will be replaced with “3/5/2018 1:36 PM” (or whatever the current date and time is).
With variable replacements you can easily compute a due date that is one year from last Tuesday. Or you can easily place the current user’s name into a string for later use. You can use these variables almost anywhere that you can specify free form values. For instance, you can set a Work Trigger due date equal to the current Record’s received date plus 60 days. You can even look up the number of days for the due date from a lookup table set up per vendor.
Another great use of variables is to use them in searches. You probably already know how to do a search for Invoices that are due from now until seven days from now. Just plug the correct dates in the Due Date search field range and go. But what if you wanted to save that search so you can use it each month? Well, it wouldn’t be much good to you because next month you don’t necessarily care about this month’s due dates! What you need are variables to help you out.
To use dates that are relative to today you can change the dates in your search to variables and then the search would be valid any time you run it. Just use a variable date range of “[DATE]” (now) to “[DATE(7)]” (now + 7 days) and then search. The search engine will put in the proper dates based on those variables and the search will work. Now you can save that search for later. Each time you run it those variables will be replaced using the then-current day’s values.
How to Use Variable Replacement
At various places in the docMgt system you have the opportunity to enter values. Record entry screens, Work Trigger input and more. Most of these places support variables by using bracket tags. Anything that is surrounded in brackets is looked at as a variable. If the bracketed value is just a word then that word is typically a data value from the current record or document. If the bracketed value has a set of parentheses then it is a function variable that will be evaluated specially.
Data Value Variables
A data value variable is simply a field name surrounded by brackets. For instance, if your current Record has a data with the name “lastname” then you can use that record’s lastname value by using “[lastname]” as a variable. You can use this in a form letter, e-form, record note, etc.
A function variable is a variable that has a name with parentheses and usually some supporting information inside the parentheses – called parameters. Some functions have a single set of parameters and some have varying numbers. For example, [SPLIT()] has a single set of parameters – [SPLIT(this-is-a-test|-|3)] means to split the string “this-is-a-test” on dashes and return the 3rd value – “a”. Whereas [DATE()] has multiple sets – [DATE(4)] means to take today’s date and add 4 days. [DATE(4,y)] means to take today’s date and add 4 years. [DATE()] means return today’s date.
We also refer to sets of functions and variables as formulas so if you see or hear that term used it is just shorthand for one or more variables or functions.
Examples and Usage
We already talked about dynamic dates by using the [DATE()] function. You can also use variables to fill in the user name of the current user or their email address. This can be handy when defining a saved search that will retrieve items associated with that user. If you use the [USERNAME] variable then share that search with others, when they run the search it will use their user name. The [IF()] statement can also be handy when trying to compare values for a search. For example, let’s say we have a record type that stores invoices. We want to find all invoices that need to be reviewed and the trick is that if the current day of the month is after the 25th then we only review those $10,000 or more in order to process invoices quickly. Else we want to review those invoices that are $1000 or more. For this case we would enter [IF([DAY]|>|25|10000|1000)] into the Amount from field. This way we find those invoices that are $1,000 or more if today is on or before the 25th. If the day is after the 25th then we will find only those invoices that are $10,000 or more.
You can also benefit from variables when adding or updating information. Let’s say we want to assign a due date to an invoice. If it is entered on or before the 15th of the month then the due date is the 1st of next month. If entered after the 15th then the due date is the 1st of the following month. To do this, use the following variable set in the Due Date field: [DATEADD([MONTH]/1/[YEAR]|0|[IF([DAY]|<=|15|1|2)])]
Let’s explain the above set of functions. First we get the first day of this month using [MONTH]/1/[YEAR]. Then we figure out whether to add 1 or 2 months to that by looking at today’s date using [IF([DAY]|<=|15|1|2)]. Then we add that number of months to the date we computed above using [DATEADD(date|0|months)].
For a current date of March 5, 2018 we have the following:
[MONTH]/1/[YEAR] = 3/1/2018
[IF([DAY]|<=|15|1|2)] = 1
[DATEADD(3/1/2018|0|1)] = 4/1/2018
For a current date of March 25, 2018 we have the following:
[MONTH]/1/[YEAR] = 3/1/2018
[IF([DAY]|<=|15|1|2)] = 2
[DATEADD(3/1/2018|0|2)] = 5/1/2018
You can add these formulas to the default value of a Record Type so that the manual entry process will auto-fill them for you. However, if you are importing values from other sources then you will need to account for these formulas yourself. Imported data does not benefit from the default values set up in Record Type fields.
I typically will prototype all my formulas in the Record screen. Just add a custom entry Record (no Record Type) and then enter the variables and click Save. Those variables are converted to their resulting values so you can see how they work.
Work Triggers derive a very big advantage from variables. Not only can they perform searches and edits as shown above but they also use conditions to decide when to do things and various actions that they perform which benefit from variables. Below are some use cases but before reading those you may want to review the workflow article series starting with Workflow Part 1.
When the system is deciding which trigger is going to be used, it evaluates the conditions which are labels “Trigger Activation Rules.” If these rules match the values and environment as needed then the trigger is used. Along with the normal “If variable = value” rules, you can get pretty creative. In the Search invoice example we had above, we limited the search to those that needed review. We could also place that formula into the Record Value Check action type to make sure all invoices needing review get routed appropriately. We can also perform checks to see if a document exists. Normally you would see if a document named “INVOICE” was present in the system. However, what if the invoices are named by their vendor name instead of a static “INVOICE” name? You can use a variable in the document field as well. It would be something like [VENDOR] to use the vendor name as the document name check.
There are several other places where variables can be used in the rules section. Rules like Team Check and Record Searching are commonly combined with variables and formulas.
Actions can be performed on the way into a trigger (Assignment Action), the way out of a trigger (Completion Action), as a button click or via a follow-up action. Along with the Workflow Part 1 article, it would be good to read through Workflow Part 2 and Workflow Part 3 before continuing.
There are a lot of action types in the workflow system – too many to go over in this article. They operate the same as in the Edit section above except that they are run in the context of workflow instead of the context of a human action such as a Record edit. Most of the action types can use variables but the main action types that are commonly used are these:
- Variable Updates (Record or Document)
- Emails (From, To, CC, BCC, Subject and Body can all use variables)
- Merge Document Category and Name
- Convert to PDF Category and Name
- Delete Documents Category and Name
- Record Notes
- Document Notes
- Search and Update
- Search and Create
- REST Calls
- Launch Web URL (button clicks only)
These can all take variables but remember the context. The Record being routed is the one whose variables are available. The exceptions are the “Search and Update” and “Search and Create” actions. These actions have access to both the current Record and the found records.
Current Variable Chart
The following variables are available at the time of this article’s writing.
|Variable||Action or Value||Example|
|[DEL]||Deletes variable from the Record||Not valid on Filters|
|[ORIGINAL]||Includes original value of the field||Only valid on Work Trigger Actions|
|[RECORD]||Summary of Record values||John Smith, 3/13/1987, Omaha|
|[RECORDID]||ID of currently effected Record||100|
|[DOCUMENTID]||ID of currently effected Document||Available when Document exists|
|[DOCUMENTNAME]||Name of Document||Scanned Page|
|[DOCUMENTEXT]||Extension of Document|
|[DOCUMENTFILE]||File name of Document||ScannedPage.PDF|
|[MONTHNAME]||Current Month Name||July|
|[DATETIME]||Current Date and Time||7/16/2015 10:48|
|[TIME]||Current Time||10:48 AM|
|[DATE(#,d)]||Date # days from now||7/16/2016|
|[DATE([EXDATE],,,,MON)]||Next Monday after [EXDATE] variable||7/18/2016|
|[DATEADD(DATE|Y|M|D|H|m|s)]||Add to given date the number of Years, Months, Days, Hours minutes and Seconds provided.
You may omit any trailing zero values but must include any leading zeros
|[DATEADD(1/1/2018|1)] = 1/1/2019
[DATEADD(1/1/2018|0|3)] = 4/1/2018
[DATEADD(1/1/2018|0|0|4)] = 1/5/2018
|[USER]||Current User’s Full Name||Admin User|
|[USERFIRST]||Current User’s First Name||Admin|
|[USERLAST]||Current User’s Last Name||User|
|[USERFULLNAME]||Current User’s Full Name||Admin User|
|[USERID]||Current User’s ID||1|
|[USEREMAIL]||Current User’s Email Addressemail@example.com|
|[USERNAME]||Current User’s Login Name||admin|
|[WFID]||ID of current Workflow item||25|
|[WFASSIGNEDNAME]||Assigned Users’ Names||admin; jsmith|
|[WFASSIGNEDEMAIL]||Assigned Users’ Email Addressesfirstname.lastname@example.org; email@example.com|
|[WFMGREMAIL]||Workflow Managers’ Email Addressesfirstname.lastname@example.org;email@example.com|
|[WFMGRNAME]||Workflow Managers’ Names||bsmith;bwhite|
|[DUEDATE]||Work Item Due Date||7/16/2015|
|[GOBALDUEDATE]||Global Work Item Due Date||7/16/2015|
|[WFLINK]||Link To Workflow Item||Workflow only|
|[MISSINGDOCS]||List of documents missing||invoice, PO, etc|
Exception for BETWEEN (B):
|Compares val1 to val2 using the operator and if true returns the true value else returns the false value.
for BETWEEN (B) operations you must supply 6 parameters with the 4th one being the TO value for the FROM (3rd) and TO (4th) combination.
Example 1: [IF(1|=|2|YES|NO)] will return NO
Example21: [IF(12=|2|YES|NO)] will return YES.
Example 3: [IF(1|B|2|3|YES|NO)] will return NO
Example 3: [IF(2|B|1|3|YES|NO)] will return YES
<> Not Equal
!= Not Equal
< Less than
> Greater than
<= Less than or equal to
=> Less than or equal to
>= Greater than or equal to
=> Greater than or equal to
S Starts With
E Ends With
* String operations are NOT case sensitive
|[DIFF]||Computes the difference between two values. For numbers the third parameter is ignored.
|[DIFF(1|3)] = 2
[DIFF(3|1)] = -2
[DIFF(1/1/2014|1/4/2017|Y)] = 3 (3 years different)
See period options below.
|[ABS]||Absolute value of incoming variable||[ABS(-22)] returns 22|
|[MIN]||Minimum of values||[MIN(1|6|5|3)] returns 1|
|[MAX]||Maximum of values||[MAX(1|6|5|3)] returns 6|
|[COUNT]||Count of values||[COUNT(1,3,4,5|,)] returns 4|
|[AVG]||Average of values||[AVG(1|6|5|3)] returns 3.75|
|[SUM]||Sum of values||[SUM(1|6|5|3)] returns 15|
|[RANDOM]||Random Value from MIN to MAX||[RANDOM] returns random number between 1 and 100
[RANDOM(1|10)] returns random number between 1 and 10
|[SPLIT]||Split value on delimiter||[SPLIT(this.is.a.test|.|2)] returns “is”|
|[REPLACE]||Replaces one value with another value||[REPLACE(test|t|x)] returns “xesx”|
|[PAD], [PADRIGHT]||Pads string with another up to length||[PAD(ABC|5|x)] returns “ABCxx”|
|[PADLEFT]||Pads left side of string||[PADLEFT(ABC|5|x)] returns “xxABC”|
|[FORMAT]||Formats value based on its formatting rules according to .NET. Works on numeric and date formats.
– Date Formats
[FORMAT(12.3|c)] = $12.30
[FORMAT(1/31/2015|YY/DD)] = 15/01
|[JOIN]||Joins collection of values. Works only on Record, Data and E-Form variable names||[JOIN(PO|;)] with a record that has 3 PO values of 12, 35 and 77 returns “12;35;77”|
|[MATH]||MATH allows you to solve simple mathematical equations. For instance you can do [MATH(1+2*3)] and it would return 7. MATH allows for parentheses in your equations so you can change the last example to [MATH((1+2)*3)] to return 9.||Available mathematic operations are as follows and are evaluated in this order.
( and ) = Parentheses (operational grouping)
^ = Exponent
* = Multiplication
/ = Division
\ = Integer Division
% = Modulus (remainder)
+ = Addition
– = Subtraction
Operators with equal precedence are evaluated left to right in the order in which they appear in the expression. This means that if your equation is “10 + 4 – 2 * 3” the order of operation would be:
1. 2 * 3 = 6 [10 + 4 – 6]
2. 10 + 4 = 14 [14 – 6]
3. 14 – 6 = 8
|[PG]||Page Number||Bates stamping only|
|[PGS]||Page Count||Bates stamping only|
|[REQUESTOR]||ID of user requesting Asset||123|
|[REQUESTORNAME]||User name of user requesting Asset||admin|
|[USERS(team|prop|del)]||Delimited list of properties for users from specified team. If team not specified then all users.
See Possible User Property Values below
|[USERS(Mgrs|EMAIL|;)] = returns semicolon-delimited list of email address for all users in the “Mgrs” team
[USERS(|NAME|;)] = returns semicolon-delimited list of full names for all users
|[TEAMS(prop|del)]||Delimited list of properties for all teams.
See Possible Team Property Values below
|[TEAMS(NAME|;)] = returns semicolon-delimited list of Names for all teams|
Possible Period values:
Y = Years as compared by year number
[DIFF(1/1/2009|12/31/2009)] = 0
[DIFF(12/31/2009|1/1/2010)] = 1
[DIFF(6/1/2009|5/30/2010)] = 1
[DIFF(6/1/2009|6/1/2010)] = 1
y = Years as compared by # of days between
[DIFF(1/1/2009|12/31/2009)] = 1
[DIFF(12/31/2009|1/1/2010)] = 0
[DIFF(6/1/2009|5/30/2010)] = 0
[DIFF(6/1/2009|6/1/2010)] = 1
M = Months
D and d = Days
B = Business Days
H and h = Hours
m = Minutes
S and s = Seconds
Possible User Property Values:
ID = IDs of users
FIRSTNAME = First names of users
LASTNAME = Last names of users
EMAIL = Email addresses of users
USERNAME = User names (login names) of users
NAME or FULLNAME = Full names (FIRSTNAME LASTNAME)of user or USERNAME if FIRST and LAST are not available
Possible Team Property Values:
ID = IDs of teams
NAME = Names of teams
Subscribe To Our Newsletter
Join our mailing list to receive the latest news and updates from our team.