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 .
Variable Replacement
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” (or whatever the current date 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.
Function Variables
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
Search
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.
Entry
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)]. Second, 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
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.
Conditions
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
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 Variables
Here is a link to the online reference for Variables. A separate reference is also available in the help section of each customer site.