Refreshing relevance

Ideally, dashboards and wizards in the console should be updated as new information arrives from the database. To make <?relevance ?> instructions automatically update, you must specify another pair of processing instructions to enclose the time-sensitive block of your document:

<?BeginRefreshRelevance?>
<?EndRefreshRelevance?>

These tags cause every <?relevance ?> tag that is contained between them to be reevaluated every time something in the console database changes.

The actual implementation of this update is important because it can affect the way that you code your HTML. During execution, the <?BeginRefreshRelevance?> tag is replaced by a <span> tag, and the <?EndRefreshRelevance?> tag is replaced by a </span> tag. When the console detects that one of the <?relevance ?> tags is changed, it updates the entire section of the document by replacing the contents of the <span> tag. You must therefore make sure that these relevance tags do not interrupt any existing <span> tags.

To correctly identify which <span> must be updated, the console assigns an ID attribute to the <span> tag that it generates to replace the <?BeginRefreshRelevance?> tag. By default, that ID is __DRRSN (an acronym for Default Refresh Relevance Section Name).

If necessary, you can specify a different ID in the refresh tags like the following code:

<?BeginRefreshRelevance id="MyRefreshSpan"?>
<?EndRefreshRelevance id="MyRefreshSpan"?>

The IDs must match exactly. Specifying your own IDs gives you a way to nest RefreshRelevance tags.

By default, anything that changes a Relevance evaluation triggers a refresh of the code block. However, you can specify which changes must trigger a refresh as well as a minimum time interval to wait. For example:

<?BeginRefreshRelevance ActionResults="00:01:00" ?>
	<?relevance (link of it & "(" & (number of results of it as string) & ")" & br) 
		of bes actions whose (state of it is "Open") ?>
<?EndRefreshRelevance ?>

This example displays a list of all the open actions as links that you can click to open the associated action document. Next to the link, the number of results for each action is displayed in parentheses. The number indicates how many of the targeted computers reported on the action.

If the action results are not changing, this block of code is static. However, when a change occurs, the 00:01:00 value for ActionResults specifies that this block is refreshed at most one time per minute. The form of these values is the standard TimeInterval string format hh:mm:ss. This is a list of the built-in refresh triggers:

Refreshes are done only at the end of each refresh cycle, not when the change is first detected. At the end of a cycle, if any of your specified types are triggered and its time interval is expired, then a refresh occurs. For more frequent updating, the RefreshCycle attribute can be used to force a refresh at the end of the refresh cycle, regardless of any changes.

You can also create blocks that can be refreshed manually by using the ManualRefresh attribute. It works in combination with a predefined script that takes the ID of the Refresh block as an argument, for example:

ManualRefresh(Clock)

This works to refresh a code block with an id=Clock:

<?BeginRefreshRelevance id="Clock" ManualRefresh="00:00:00" ?>
	<P> The current time is: <?relevance now ?> </P>
<?EndRefreshRelevance id="Clock" ?>
<P> <Button onclick='ManualRefresh("Clock")'>Refresh</Button> </P>

You can also call the script function with no parameters:

ManualRefresh()
ManualRefresh("")

This code refreshes the default unnamed refresh block. To refresh all the blocks, use:

ManualRefreshAll()

You can set multiple clocks to satisfy different refresh needs:

<?BeginRefreshRelevance ManualRefresh="00:00:00"?>
	<?relevance now ?>
<?EndRefreshRelevance?>
<?BeginRefreshRelevance id="Foo" ManualRefresh="00:00:00"?>
	<?relevance now ?>
<?EndRefreshRelevance id="Foo"?>
<P> <Button onclick='ManualRefresh()'>Refresh first clock</Button> </P>
<P> <Button onclick='ManualRefresh("Foo")'>Refresh second clock</Button> </P>
<P> <Button onclick='ManualRefreshAll()'>Refresh all clocks</Button> </P>

You can also associate refresh operations with a JavaScript by using RegisterRefreshHandler. You can use the RegisterRefreshHandler function in both the console and Web Reports, but in Web Reports it is ignored, and your handler is never called. Because a Web Report is static, it does not support refreshing relevance.