HistoryOf function

Revision as of 14:25, 12 February 2019 by Nancy Sabo (talk | contribs) (Syntax for the CONDITION field)

Revision as of 14:25, 12 February 2019 by Nancy Sabo (talk | contribs) (Syntax for the CONDITION field)

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:

[Value]