Difference between revisions of "HistoryOf function"
Nancy Sabo (talk | contribs) |
Nancy Sabo (talk | contribs) (→Notes) |
||
| (3 intermediate revisions by the same user not shown) | |||
| Line 11: | Line 11: | ||
===Available Parameters=== | ===Available Parameters=== | ||
| − | + | ||
| − | + | {| class="wikitable" | |
| − | + | |'''Parameter''' | |
| − | + | |'''Definition''' | |
| − | + | |- | |
| − | + | |'''FIELDNAME''' | |
| + | |Specify the fieldname to query. | ||
| + | |- | ||
| + | |'''CONDITION''' | ||
| + | |Specify the condition you wish to search. This can be a specific field value (old or current), a date (used to specify when an update took place), or even a specific user who made an update. Available fields are : [Value], [OldValue], [UpdatedTime], [UpdatedBy]. | ||
| + | |- | ||
| + | |'''TEMPLATE''' | ||
| + | |Specify how the results will be displayed. Available fields are : [Value], [OldValue], [UpdatedTime], [UpdatedBy]. Additional text can be added for clarity. | ||
| + | |- | ||
| + | |'''SORTFIELD''' | ||
| + | |Specify which parameter value to use as the sorting rule. This can be [Value], [OldValue], [UpdatedTime], [UpdatedBy]. | ||
| + | |- | ||
| + | |'''SORTDIRECTION''' | ||
| + | |Specify ''asc'' (ascending) or ''desc'' (descending), to control in what order results are sorted. | ||
| + | |- | ||
| + | |'''LIMIT''' | ||
| + | |The number of matching entries to be displayed. | ||
| + | |} | ||
* You may leave a parameter space empty, although the double colon separators must remain in place. You must specify FIELDNAME, plus either CONDITION or TEMPLATE, at a minimum. | * You may leave a parameter space empty, although the double colon separators must remain in place. You must specify FIELDNAME, plus either CONDITION or TEMPLATE, at a minimum. | ||
| Line 38: | Line 55: | ||
<pre>@HistoryOf(Status::::Changed from [OldValue] to [Value] by [UpdatedBy] on [UpdatedTime]::[UpdatedTime]::desc::1)@</pre> | <pre>@HistoryOf(Status::::Changed from [OldValue] to [Value] by [UpdatedBy] on [UpdatedTime]::[UpdatedTime]::desc::1)@</pre> | ||
| − | ===Syntax for the CONDITION | + | ===Syntax for the CONDITION parameter=== |
When querying a numeric field type, you can use the comparison operators: >, <, >=, <=, =. | When querying a numeric field type, you can use the comparison operators: >, <, >=, <=, =. | ||
| Line 56: | Line 73: | ||
* The TEMPLATE parameter can include HTML tags for formatting assistance, such paragraph or break tags: | * The TEMPLATE parameter can include HTML tags for formatting assistance, such paragraph or break tags: | ||
| − | [Value] | + | <pre><p>[Value]</p></pre> |
| − | [[ | + | [[Category:Enhancements]] |
| − | [[ | + | [[Category:Variables]] |
Latest revision as of 13:27, 12 February 2019
Contents
Overview
This function allows you to search for specific field history entries. Please note: use of this function requires that the Track Changes field permission is enabled first.
Once there is Field History to query, the function itself will be available via the Syntax Checker. To access the Syntax Checker: enter Edit mode for the record, then click on Options-->Configuration Mode, and select Syntax Checker Tool. Once the Syntax Checker window appears, you will be able to use the HistoryOf function. See below for examples.
Function syntax
@HistoryOf(FIELDNAME::CONDITION::TEMPLATE::SORTFIELD::SORTDIRECTION::LIMIT)@
Available Parameters
| Parameter | Definition |
| FIELDNAME | Specify the fieldname to query. |
| CONDITION | Specify the condition you wish to search. This can be a specific field value (old or current), a date (used to specify when an update took place), or even a specific user who made an update. Available fields are : [Value], [OldValue], [UpdatedTime], [UpdatedBy]. |
| TEMPLATE | Specify how the results will be displayed. Available fields are : [Value], [OldValue], [UpdatedTime], [UpdatedBy]. Additional text can be added for clarity. |
| SORTFIELD | Specify which parameter value to use as the sorting rule. This can be [Value], [OldValue], [UpdatedTime], [UpdatedBy]. |
| SORTDIRECTION | Specify asc (ascending) or desc (descending), to control in what order results are sorted. |
| LIMIT | The number of matching entries to be displayed. |
- You may leave a parameter space empty, although the double colon separators must remain in place. You must specify FIELDNAME, plus either CONDITION or TEMPLATE, at a minimum.
- For the FIELDNAME parameter, you can use a Standard or Custom fieldname, or a custom fieldID.
Examples
Show 1 record, where the Application Name field was updated after February 1, 2019. Results will be sorted in descending order, by the field value.
@HistoryOf(Application Name::[UpdatedTime]>2019-02-01::::[Value]::desc::1)@
Show the last person to set the status to Approved (if it had that status more than once), along with the date and time.
@HistoryOf(Status::[Value]='Approved'::Update to [Value] by [UpdatedBy] at [UpdatedTime]::[UpdateTime]::desc::1)@
Show a maximum of 5 matches where the Description field contains the string 'test', with no display template specified, sorted in descending order by UpdatedTime.
@HistoryOf(Description::[Value] like %test%::::[UpdatedTime]::desc::5)@
Show the last person to change the Status of the record, showing the old and current values, with date and time.
@HistoryOf(Status::::Changed from [OldValue] to [Value] by [UpdatedBy] on [UpdatedTime]::[UpdatedTime]::desc::1)@
Syntax for the CONDITION parameter
When querying a numeric field type, you can use the comparison operators: >, <, >=, <=, =.
[Value]>=30
If you want to check whether a text field value contains a piece of text, use LIKE and %.
[Value] LIKE '%hello%'
For a custom date or datetime field, you can use the comparison operators: >, <, >=, <=, =. The syntax for date values is either: YYYY-MM-DD or YYYY-MM-DD HH:mm:ss.
[Value] > '2019-01-23 13:30:40' AND [Value] < '2019-01-30'
- Date formatters also apply to the [UpdatedTime] field.
Notes
- You can also use only the base search format, if you wish: @HistoryOf(FIELDNAME)@
- The TEMPLATE parameter can include HTML tags for formatting assistance, such paragraph or break tags:
<p>[Value]</p>
