Many System Variables require that you specify the name of a specific Content List object for the System Variable to work properly. For instance, calling the number of times a Timeline Activity has run requires that you specify the name of the activity in the System Variable, using the syntax:

{ACTIVITY_NUM_TIMES_RUN:ActivityName}

...where ActivityName is the name of the Timeline Activity you are evaluating. If you use spaces in the Activity name, then you must enclose the name in quotation marks, e.g.:

{ACTIVITY_NUM_TIMES_RUN:"Activity Name"}

...to ensure that the name is parsed properly. Activity names that don't contain spaces may be referenced without the quotation marks.

As a best practice, you may wish to consider using quotation marks any time you reference an object name in a system variable.

Most system variables can be configured via the “group” Modifier, which limits the results of a system variable such that it will return only results belonging to the specified group. Use the following syntax to add a group restriction to a SysVar tag:

{SYSTEM_VARIABLE, group=GroupName}

Encoding types are special characters put inside system variable tags to force the tag to return a certain type. These are often used to prevent improperly encoded values from breaking a query. The format used to specify an encode type is as follows:

{encode-typeSysVar}

Process Director v4.0 and higher can be set to automatically encode all System Variables on a Form as HTML, which eliminates the need to use the "!" encode symbol. To set this behavior as a default, you must set the DefaultHTMLEncode custom variable to "true". You can force Process Director not to encode as HTML by using the "|" encode symbol.

Where encode-type can be any one of the following symbols:

Examples

SELECT * FROM MyTable WHERE col1 = '{$:text1}'

The $ encode will safely type the value of "text1" from:

Bob's Place

To:

Bob''s Place.

SELECT * FROM MyTable WHERE col1 LIKE '%{~:text1}%' ESCAPE '\'

When used in in a LIKE statement, the ~ encode type will perform the same safe encoding as the $ does. Additionally, when adding the ESCAPE clause to the SQL statement, values that require escapes for special characters will be added to the encoding. So, for a value of:

100%

The combination of the ~ encode and the ESCAPE clause in the example will produce an encoded value of:

100\%

In order to reduce security issues, Process Director v4.5 and higher issues a warning for using non-encoded System Variables in the SQL Statements used by Business Values or Custom Tasks. A Custom Variable setting, fAllowUnencodedSysvarsinBV, will, when set to "false", prevent users from saving any object that has unencoded variables in a SQL statement.

Pre, post, and null are options specifying what text a system variable will display before the result, after the result, and if there is no result, respectively. Pre and post will display when the system variable result isn't null, and the null text will display otherwise. To specify the Pre, Post, and Null values in a SysVar tag, use the following format:

{SYSTEM_VARIABLE pre="Text before Var", post="Text after Var", null="Value if Null"}

String system variables can be manipulated by using case and substring Modifiers.

Examples:

The Case Modifier will convert string text into all upper case or lower case as desired.

{:someFormField, case=upper|lower}

The substring Modifier enables you to extract a desired substring by identifying the starting character location with the "subStart" Modifier, and the length of the substring with the "subLength" Modifier. The position of the "subStart" Modifier is zero-based, meaning that the first character position is 0, rather than 1.

//This syntax will render the string "abcdefghijklmnop" as "ghijklmnop".
{:someFormField, subStart=6, subLength=10}

The Case Modifier can also be used in conjunction with the substring Modifiers.

//This syntax will render the string "abcdefghijklmnop" as "GHIJKLMNOP".
{:someFormField, case=upper, subStart=6, subLength=10}

Pattern and Replace are Modifiers that can be added to any system variable. Data in the result of a system variable matching a regular expression specified in the Pattern Modifier will be replaced as specified in the Replace Modifier. See Microsoft’s documentation on regular expressions in .NET for more information regarding regular expressions. The Trim Modifier can also be added to any system variable. When set to 1, it will trim leading and trailing spaces off the result of the system variable.

Examples:

This Control Tag will replace the text “some text” in a form field with the text “other text”:

{:someFormField, Pattern="Some text", Replace="Other text", Trim=1}

This System Variable tag will remove any semicolons from the current user’s name:

{CURR_USER, Pattern=";", Replace=""}

You can also combine Encoding characters and Pattern/Replace together to modify strings. For instance, the sample below shows various ways to display the selected items from a ListBox.

For process Director v5.1 and higher, string variables enable you to use an "indexOf" modifier to return the 0-based index of the starting location for a specified substring. If the substring isn't found, this variable will return "-1". The substring search is case insensitive.

Example

In this example, a form field, "myField" contains the following text string: "I Do Approve This". To find the starting index of the substring "approve", the following syntax would be used:

{:myField, indexOf="approve"}

The System variable will, in this case, return "5".

Some System Variables return information about Timeline activities. These activities and steps may be run several times over the course of a process. Using the “instance” Modifier, you can specify which instance or instances of the activity you are referring to.

To get a total for all instances, set the instance Modifier to “all”. This will add up the results of the System Variable for every time the activity or step has run within a Timeline instance, and return a concatenated list of all users that have completed the activity, including all instances of that activity when it is iterating.

To get the value for the most recent instance, set the instance Modifier to 0. To get the value for the second most recent instance, set the instance Modifier to -1. To get the value for the third most recent instance, set the instance Modifier to -3, and so on.

To get the value for the first instance of the activity in the Timeline instance, set the instance Modifier to 1. To get the value for the second instance of the step or activity, set the instance Modifier to 2, and so on.

Examples:

{ACTIVITY_RUN_TIME:"Some Activity", instance=all}

This system variable will return the total time the activity has run in the Timeline instance.

{ACTIVITY_RUN_TIME:SomeActivity, instance=0}

This system variable will return the time it took the most recent instance of the activity to run in the Timeline instance.

{ACTIVITY_RUN_TIME:"Some Activity", instance=-2}

This system variable will return the time it took for the third most recent instance of the activity to run.

{ACTIVITY_RUN_TIME:SomeActivity, instance=1}

This system variable will return the time it took for the first instance of the activity to run in the Timeline instance.

Any time a system variable returns a comma-separated list of values, you can use the modifier format=distinct to remove any duplicate values from the list.

A number of general formatting and value options apply to Form Field values.

Format:

{FORM:SomeFieldName, format=Formatter}

• Currency: Formats the system variable into a format representing currency. Applies only to fields configured as a "Number" data type, or to Calculation fields.
  A field containing the value "2245" would be displayed as "$2,245.00".
• [.NET Format String]: For form fields and case properties that are specified as a "Number" data type, you can use a .NET format string to format a numeric result. Process Director supports the .NET format strings described on MSDN here and here. For instance, you can use a format string to display a numeric field to 2 decimal places. In this example, a field value of "32.5675" would be displayed as "32.57" by using the syntax:
  {FORM:MyNumberField, format="##.##"}
  Similarly, a Calculation field can convert a field value of "0.2557" to "25.57%" by using the syntax:
  {CALC, formula="{FORM:MyNumberField}*100", format="##.##"}%
Additionally, the Microsoft format string specifiers for numeric values can also be used. For instance, a value of "1052.0329112756" can be converted to a scientific (exponential) notation result of 1.052033E+003 by using the syntax:
  {FORM:MyNumberField, format="E"}
• Value: Returns the value of a dropdown field. This option is generally unnecessary, since the value of a Dropdown controls is returned by default, e.g., {:FormFieldName} will return the value selected in the Dropdown control.
• String: Returns the text in an Input field, or the displayed text of a Dropdown field.
• Friendly: When used in conjunction with a Form Field Picker, returns the friendly field name of a form field.
• ClientID: Returns HTML ID of the control suitable for JavaScript.
• DisplayString: Returns the displayed text of a Dropdown field instead of the value, e.g., {:FormFieldName, format=DisplayString}
• Length: Returns the length of a STRING value stored in a form field.
• first_value: Returns the first value saved in the field, when Form Field Auditing is enabled.
• prev_value: Returns the immediately previous value saved in the field, when Form Field Auditing is enabled.
• name: For a TabStrip control, this formatter will return the name of the active Tab, instead of the Tab ID.
• count: For Process Director v5.31 and higher, list controls that have multiple selection enabled, such as the UserPicker and List Box, as well as Input controls that display comma-separated lists, can use this formatter to return the number of items in the list.

ROW_NUM:

{FORM:SomeFieldName, ROW_NUM=2}

If this form control is part of an array, returns the value specified by the ROW_NUM Modifier. The Row Number Modifier can also be specific with a shorthand alias:

{FORM:SomeFieldName:2}

In this example, the row number is specified by the ":2" syntax.

Separator

{FORM:someColumnFieldName, SEPARATOR=|}

If this form control is part of an array, a list of users, or a list of groups, this option specifies which character will be used to separate the different values in the different elements of the array. By default, the separator is a comma. The Separator modifier can also be used for any list field that can use the "format=count" formatter.

System variables that return numbers will have the following options:

Format

{FORM:SomeFieldName, format=FormatType}

• Currency: Formats the system variable into a format representing currency (e.g. $22.99).
• Number: Ensures that a system variable returns an integer.

{FORM:SomeFieldName, digits=Number}

Adding the formatter digits=n, where "n" is the number of digits, will return the number formatted as an n-digit number. This Modifier will PAD the form field value with 0's, and it won't truncate. Example usage: A numeric form field using the Modifier {FORM:fieldname, digits=3} and that contains the value "23" will return "023".

For v5.23 or higher, this formatter is available for use for any system variable, and will unconditionally convert any value to digits. Passing a non-numeric value will result in a n-digit number of 0s.

System variables that return a datetime value have the several modifiers that enable a specified time increment to be added or subtracted from any system variable that returns a date value. For example, let's say you use a system variable that returns a datetime value like:

{ACTIVITY_START_DATE:ActivityName, BUSINESS_DAYS=10}

If the activity begins on December 1, 2023, this system variable will return a value of December 15, 2023, by adding 10 business days, as December 2-3 and December 9-10 are weekend days.

Similarly, you can use a negative value for the modifier to subtract time from a datetime value. For example:

{ACTIVITY_START_DATE:ActivityName, BUSINESS_DAYS=-10}

In this case, for an activity that begins on December 1, 2023, the system variable would subtract 10 business days to return a value of November 17, 2023.

The following date modifiers are available to implement this function.

• YEARS: adds a specified number of years to a DateTime or TimeSpan SysVar result.
• MONTHS: adds a specified number of months to a DateTime or TimeSpan SysVar result.
• DAYS: adds a specified number of days to a DateTime or TimeSpan SysVar result.
• HOURS: adds a specified number of hours to a DateTime or TimeSpan SysVar result.
• MINUTES: adds a specified number of minutes to a DateTime or TimeSpan SysVar result.
• SECONDS: adds a specified number of seconds to a DateTime or TimeSpan SysVar result.
• BUSINESS_DAYS: adds a specified number of business days to a DateTime or TimeSpan SysVar result.
• BUSINESS_HOURS: adds a specified number of hours to a DateTime or TimeSpan SysVar result. By default, business hours are from 8:00am to 6:00pm, but business hours can be configured in the vars.cs file via the BusinessHourStart and BusinessHourStop variables.
• FULLYEARS: Adds the number of full, 365-day years for a DateTime or Timestamp SysVar result.
• FULLMONTHS: Adds the number of full, 30.414-day months for a DateTime or Timestamp SysVar result.
• FULLDAYS: Adds the number of full, 24-hour days for a DateTime or Timestamp SysVar result.
• OR NEAREST BUSINESS DAY: This option instructs all date system variables to return the evaluated date if that date is a business day, and otherwise to return the previous or next business day, as directed. The time portion of the date value is unaffected, only the date portion is (potentially) modified. The syntax is {DATETIME_VARIABLE, OrNearestBusinessDay=Prev|Next}.

The Types YEARS, MONTHS, DAYS, HOURS, and MINUTES use "calendar" elapsed times, which is to say that, if a time span crosses a calendar date, it counts as a full increment of the selected calendar Type (Day, Month, etc.). For example, a time span from 11:59 PM on Dec 31 to 12:01 AM on Jan 1 is only a two-minute time span, but it will be counted as 1 day in DAYS, 1 month in MONTHS, or 1 year in YEARS. Any time span which crosses a date will be counted as a full increment of the Type chosen.

The Types FULLDAYS, FULLMONTHS, and FULLYEARS compare the time span to a pre-defined length of time. FULLDAYS returns 1 for every actual 24 hours elapsed, FULLMONTHS returns 1 for every 30.416 days, and FULLYEARS returns 1 for every 365 days. Using these Types, the time span from 11:59 PM on Dec 31 to 12:01 AM on Jan 1 would return 0 for all three types.

Format

Datetime system variables also have a format Modifier that can be used to determine how the date and time are displayed. The Format modifier can be set to any combination of the following options:

{FORM:MyDateField, format=option, years=numberOfYears, months=numberOfMonths...}

• d: displays the current day of the month as a number (1 – 31)
• dd: displays the current day of the month as a number, padding to two digits with a zero if necessary (01 – 31)
• ddd: displays the abbreviated name of the day (Sun. – Sat.)
• dddd: displays the full name of the day (Sunday – Saturday)
• h: displays the hour as 1-12. Without specifying AM or PM, 1:00pm is indistinguishable from 1:00am (and so on) with this formatting option.
• hh: displays the hour as 01-12. Padding using a zero is applied to ensure that the value returned is two characters long. Without specifying AM or PM, 1:00pm is indistinguishable from 1:00am (and so on) with this formatting option.
• H: displays the hour as 0-23.
• HH: displays the hour as 00-23. Padding using a zero is applied to ensure that the value returned is always two characters long.
• m: displays the current minute as a number 0 – 59
• mm: displays the current minute as a number 00 – 59. Left padding using a zero is added to ensure the return value is two characters long
• M: displays the month as a number 1 – 12
• MM: displays the month as a number 01 – 12. Left padding using a zero is added to ensure the return value is two characters long.
• MMM: returns the abbreviated name for the month (Jan. – Dec.)
• MMMM: returns the full name for the month (January – December)
• s: displays the seconds as a number 0 – 59
• ss: displays the seconds as a number 00 – 59. Padding using a zero is added to the left of the return value to ensure it is two characters long.
• t: displays an A if the time is before noon or P if it is after noon
• tt: displays A.M. if the time is before noon. Otherwise displays P.M.
• y: displays the year as a one or two digit number. The first two numbers of the year are always omitted. The third digit of the year is omitted if the year is between ’00 and ’09 (e.g. 1, 17, 93)
• yy: displays the last two digits of the year. (e.g. 48, 67, 73)
• yyyy: displays all four digits of the year. If the year is less than four digits long, zeros are added to pad the year value to four digits (e.g. 1982, 2009)
• separators (/ : “ ‘): quotation marks, apostrophes, colons, and slashes can be added to the datetime formatting. They will displayed literally, and can be used to separate different elements of the datetime string.
• AUTO: This option is valid for TimeSpan values only, and will format the result into the nearest logical unit of time for human consumption. The result will include a number as well as a unit of time. For example, a TimeSpan of 25 hours would evaluate to “1 day”, while a period of 2 hours would evaluate to “2 hours”.

Timespan system variables return amounts of elapsed time. They are distinct from Datetime system variables in that they don't return specific points in time, but amounts (durations) of time. For example, let's calculate a Timespan between two dates:

• Date 1: 1/1/2015 8:00:15 AM
• Date 2: 8/18/2015 1:30:30 PM

The resulting Timespan returned from calculating the difference between these two dates would be "229.05:30:15 ", which is a duration of 229 days, 5 hours, 30 minutes, and 15 seconds.

Format

You can specify the format of Timespan system variables using the Format= option.  The Format= option determines how the Timespan is displayed in text. The string specifying the format of a Timespan can have any text, and should also include at least one of the options below. Timespan formatters must be enclosed in square brackets, as shown below.

For each option below, we will use the sample Timespan of "229.05:30:15" to calculate the sample values.

• [d]: the days portion of the timespan ( Sample value: 229).
• [D]: the duration of the timespan expressed in days, padded to two decimal places (Sample value: 229).
• [h]: the hours portion of the timespan (Sample: If the time is 5:47.21 am, the value will return: 5).
• [H]: the duration of the timespan expressed in hours (Sample value: 5501)
• [m]: the minutes portion of the timespan (Sample: If the time is 5:47.21 am, the value will return: 47).
• [M]: the duration of the timespan expressed in minutes (Sample value: 330090).
• [s]: the seconds portion of the timespan (Sample: If the time is 5:47.21 am, the value will return: 21).
• [S]: the duration of the timespan expressed in seconds (Sample value: 19805415).

Each of these options can be modified to pad the variable to two or three characters in length, by changing the format string from [x] to [xx] or [xxx] respectively. For example, to pad the seconds portion of the timespan to three characters in length, you'd use the format string [sss], and to pad the duration of the timespan in days to two characters in length, you could use the format string [DD].

Formatting strings can be concatenated into a single formatting string to return complex formatting results for a timespan system variable. For example, a DateDiff Form field (Form Control tag) formatted as:

{DateDiff:FieldName, Date1=Date1, Date2=Date2,FORMAT="[d] days, [h] hours, [m] minutes"}

Might return the notional result:

2 days, 4 hours, 23 minutes

Process Director enables you to create custom variable placeholders by using the generic Variable selector, or the generic {VARIABLE:VarName} syntax.

This feature enables you to create generic variables for use with URL parameters to set the default value of a field or to pass a filter parameter to a Knowledge View. Detailed explanations of how to use generic variables with URL parameters can be seen in the Knowledge View and Form topics. Additionally, this feature can be used to pass chart parameters, as described in the Drill down target section of the Charts topic that uses an example showing the {VARIABLE:VarName} syntax.

For Process Director v5.34 and higher, System Variables that return the number of attachments for Timelines (TIMELINE_ATTACHMENT_NUM), Forms (FORM_ATTACHMENT_NUM), etc., enable the use of wildcards and lists of group names in the system variables. For example, if you have two groups named "Final Drafts" and Final Documents", setting the wildcard for the group name as "Final%" will return attachments in both groups.

Example

{TIMELINE_ATTACHMENT_NUM, GroupName="Final%"}