Introduction
From VisualCron version 4, the handling of variables has been changed. In previous versions, variable handling was only reached from Notifications. Now, variables can be reached from almost any place in the client application at any time. Also, the new variable handling offers greater customization possibilities. For example, when presenting a date variable, the format of the date can be totally customized.
Using variables
The variables are accessed from the main menu Server > Global objects >Variables window or at the status bar of each window that is able to use variables. Those windows have a Variables button in the status bar.
Almost all fields in the windows that have the Variables button can use variables. You can check if a field is able to receive variables if you try to drag and drop a variable to that field. If yes, the text field will go light blue while hovering over the field and a drop will be possible. If no, no drop will be possible.
The tree view is a hierarchy of variables. When opening at the (bottom) VisualCron variables -> Jobs item, you will see that your current Job is noted with a green arrow and its Tasks are reflected in the tree. Each Job can be browsed to show the Triggers, Tasks and variables connected to it.
The Variable Key text box
When a variable is selected in the tree view, the key name is automatically added to the Variable Key text box. At the same time, VisualCron tries to show the current value in the Value Preview text box. The Variable Key text box can be manually changed by you. For example, you may want to control the format of a date. The preview is updated in real time.
Hierarchy of variables
VisualCron is presenting different kind of variables. The tree, especially for the VisualCron variables root is built up as a hierarchy. In the root there are Jobs. When entering a Job, you can reach its triggers, Tasks etc. A trigger in turn may have a result object which can be browsed.
Parameter delimiters
By default, the parameters supplied to a Variables is using pipe (|) or comma (,). If you have these in the string already you might want to use an alternate parameter delimiter. You can do this by starting the parameters with the character you want to split with. For example, if you want to use @ as parameter delimiter you can create a Variable like this: {FILE(@Content@c:\textfile.txt)}
The root variables
Functions
Functions contains a set of string and path functions that can be useful for editing/changing text.
System variables
These are values collected from the current computer/server, such as Environment and Memory variables and system uptime.
Date variables
The current date, can be formatted in your way. There are also some preformatted variables. See here for more date/time variable details.
File variables
Variables related to files. For example, the Content argument gives the text content of a file.
Folder variables
Variables concerning folders. Currently this group contains paths to the current and system folder.
VisualCron variables
These are the most powerful variables which let you access a large part of your VisualCron Job and Task data.
User defined variables
You are able to create your own static or dynamic Variables - with different value types. To Add/Edit/Remove a Variable you ca either click at the Add/Edit/Delete buttons or create Tasks (Set Variable, Remove Variable, Calculate Variable) that does this.
The format of a variable
The below text is an example of a variable key. The first part begins with an "{" and the following text what kind of root variable to look for. In this case a Task. In the Manage variables window you can see, once you have selected a variable, the format of the variable in the status bar. In this case: {TASK (TaskId,Name)}. The parts within the parenthesis are the arguments. The first argument is the id of the Task. This id is generated by VisualCron once the Task has been created. The second argument "Name" tells us that once we have found the Task from it's id, we want to get its name.
Variable Key example: {TASK(7b9a0b42-ec36-482e-bd04-93ef8b655108,Name)}
Drag'n drop
By holding down your left mouse button on a variable a drag and drop action will start. While holding it down you can drag the variable to a field where you want to use it. Not all fields can receive variables. You can see if a field supports variables by moving it over a field. If a drop symbol becomes visible and the color of the field turns light blue you are able to release the mouse and the variable will be placed into the field.
Value preview
When clicking on a variable, VisualCron will try to obtain the value of the variable in real time. This value will be shown in the yellow Value Preview text box.
Active Job/Task vs specific Job/Task
In the Job list you will see a Job listed as "Active Job" with a red Job icon. An active Job could be any Job or Task that VisualCron currently is processing. All Jobs you have created are listed below the active Job. The Jobs that are listed below that active Job points to a specific Job or Task. For example, when using the Job.Name variable you will always get the same name (unless the name is changed) for that particular Job. When using the Active Job you will get the name of the Job that is currently processed when the variable is replaced.
The advantage of using "Active Job" is that you can prepare a Notification for example with Active Job or Task parameters. In the report from the Notification you will get different results, depending on the Job or Task that is being run. In that way Notifications can be reused.
The advantage of using a variable from a Job defined by you is that you know exactly which variable you get. You will always get that variable from that particular Job or Task.
Current Job/Task
The current Job or Task is the Job or Task that you currently are editing. It is marked by a green arrow to the right of the Job or Task name. It is there to help you find the Job or Task currently being edited. Note that the Job or Task is not available in the tree view until you have added it.
Previous Task
You can always refer to the last run Task by using the PrevTask Identifier, like this:
{TASK(PrevTask,Name)}
Triggers
The trigger is the part of the Job that makes a Job run. You are able to get information from that trigger.
Last Trigger and Specific trigger
The last trigger always exist as a part of the trigger tree. It represents the last trigger that executed your Job. Remember that you may have several triggers for one Job. By using the last trigger you can automatically get information about the last trigger without explicitly pointing to a specific trigger.
There are some things to consider about Last Trigger. If you use different kinds of triggers, for example one Event trigger and one Time trigger you can reach the generic variables like name, last run etc. What you can't always get is specific variables, like if you are pointing to a file name of the File event. That variable will not exist in the Last Trigger if the last trigger was a time trigger.
If you want to be sure that you always get specific trigger information you must point out a specific trigger in the tree view.
Trigger result variables
Some variables exist when a trigger has been added, for example a trigger name. Other variables are result variables and are created/updated when a trigger has been run. For example, when using a File event trigger you are watching a folder. You have a folder name and a file mask. These variables are available instantly.
Now, let's say you are monitoring for changes in *.txt files. Since you are using a file mask you may not know exactly which file that was changed. Now, with trigger result variables you are able to get that information. This information is stored after the trigger has been run and is instantly available for usage before the actual Job has been started.
Especially Event triggers have many variables that are available for usage when they have been triggered. Below is a description of what those variables contain.
Note that result variables are stored and always available once created. If your Job was triggered once you have the result variables. If you now go and change the actual trigger, the field values of the trigger will be changed but the actual result will remain until the trigger is being triggered again.
File event result variables:
Folder path
The folder path that the event is watching.
File mask
The file mask that was used when watching.
Type of change
Gets the type of folder event that occurred.
Path
Gets the fully qualified path of the affected file or folder.
Name
Gets the name of the affected file or folder.
More information:
Microsoft file system event arguments
EventLog event result variables:
Host
Name of the computer that generated this event.
Category
Translation of the subcategory, the translation is source specific.
Event code
Value of the lower 16-bits of the EventIdentifier property. It is present to match the value displayed in the Windows NT Event Viewer. Note that two events from the same source may have the same value for this property, but may have different severity and EventIdentifier values.
Event id
Identifier of the event. This is specific to the source that generated the event log entry and is used together with SourceName, to uniquely identify a Windows NT event type.
Event type
Windows Server 2003, Windows 2000, and Windows XP: Type of event in a number representation. See Type for string representation.
Value Meaning:
1 Error
2 Warning
3 Information
4 Security audit success
5 Security audit failure
Date created
The time the Source generated the event.
Log file
Name of Windows NT event log file. This is used together with RecordNumber to uniquely identify an instance of this class.
Message
Event message as it appears in the Windows NT event log. This is a standard message with zero or more insertion strings supplied by the source of the Windows NT event. The insertion strings are inserted into the standard message in a predefined format. If there are no insertion strings or there is a problem inserting the insertion strings, only the standard message will be present in this field.
Record number
Identifies the event within the Windows NT event log file. This is specific to the log file and is used together with the log file name to uniquely identify an instance of this class.
Source
Name of the source (application, service, driver or subsystem) that generated the entry. It is used, together with EventIdentifier to uniquely identify an Windows NT event type.
User name
User name of the logged-on user when the event occurred. If the user name cannot be determined, this value will be NULL.
Type
Type of event. This is an enumerated string. It is preferable to use the EventType property rather than the Type property.
Value Meaning
1 Error
2 Warning
4 Information
8 Security audit success
16 Security audit failure
More information:
Process event result variables:
Process name
Name of the process that was started/stopped.
Description
Description of an object.
Created date
Date the process began executing.
Path
Full path to the executable file of the process. Example: C:\WINDOWS\explorer.exe.
Command line
The command line that started a specific process, if applicable.
Process id
Global process identifier that you can use to identify a process.
More information:
Service event result variables:
Name
Unique identifier of the service that provides an indication of the functionality that is managed.
Display name
Display name of the service.
Path
Full path to the service binary file that implements the service.
State
Current state of the base service.
Values are:
•"Stopped"
•"Start Pending"
•"Stop Pending"
•"Running"
•"Continue Pending"
•"Pause Pending"
•"Paused"
•"Unknown"
Status
Current status of the object. Various operational and non-operational statuses can be defined. Operational statuses include: "OK", "Degraded", and "Pred Fail" (an element, such as a SMART-enabled hard drive, may be functioning properly but predicting a failure in the near future). Non-operational statuses include: "Error", "Starting", "Stopping", and "Service". The latter, "Service", could apply during mirror-resilvering of a disk, reload of a user permissions list, or other administrative work. Not all such work is on-line, yet the managed element is neither "OK" nor in one of the other states.
Values are the following:
•"OK"
•"Error"
•"Degraded"
•"Unknown"
•"Pred Fail"
•"Starting"
•"Stopping"
•"Service"
Exit code
Windows error code that defines errors encountered in starting or stopping the service. This property is set to ERROR_SERVICE_SPECIFIC_ERROR (1066) when the error is unique to the service represented by this class, and information about the error is available in the ServiceSpecificExitCode property. The service sets this value to NO_ERROR when running, and again upon normal termination.
Service specific exit code
Service specific error code for errors that occur while the service is either starting or stopping. The exit codes are defined by the service represented by this class. This value is only set when the ExitCode property value is ERROR_SERVICE_SPECIFIC_ERROR (1066).
More information:
Registry event result variables:
Hive
Name of the hive (subtree) that contains the key (or keys) that is changed. For example, HKEY_LOCAL_MACHINE.
Registry key path
Path to the registry key. For example, "SOFTWARE\Microsoft\WBEM\Scripting".
Registry value name
Name of the value in the registry key. For example, in the registry key HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\WBEM\Scripting you can detect changes in the value Default Namespace.
Value
Value of the specific specific key. Only available when using Registry Value Change event.
More information:
Special characters
You can write special characters like new line etc using this format: https://docs.microsoft.com/en-us/dotnet/standard/base-types/character-escapes-in-regular-expressions inside the String.Print Variable: {STRING(Print|\n)}
Custom event result variables
Currently no result variables exist for this event type.
Missing a variable or field where you want to use a variable? If you feel that you could have usage of a certain variable in a certain place that currently not exists, please send a mail to support@visualcron.com. We will try to extend this functionality in the way you want it.
Limitations
Current state of tree view
The tree view shows the current state. The available variables are those that exist by the time you open the variables window. Variables added after this are not added to the tree view until you open it the next time. Also, a Job is not available until it has been added to the server.
Local previewing
When previewing the variables at the client, File variables like content, are based on files in the client. If you get a message that a file does not exist, the file may exist in the server hosted at another location.
2 levels of variable replacing
There is a limitation how deep VisualCron will go when searching for variables to replace. The reason for this is performance and also that there must be an end in searching for variables sometime. For example, let say you have a variable in your Name field of your first Job. The text in the Name field is: "Job {DATE (Week)}". When using the name variable of this first Job you will get the text "Job" and the current week number. Now, suppose you have a second Job. For some reason you want to use the value of the Name field of the first Job in the Name of your second Job. Now you add a specific variable pointing to the first Job in the Name field, for example "{JOB(id,Name)}". When executing the second Job, VisualCron will first try to reach the name of the first Job (level 1) and then when reaching that Job it finds that it contains the variable week. It will replace that variable too (level 2). This is the end of the search and VisualCron would not have continued if the first Job pointed to another Job that used another variable.
Old variables supported for a limited time
Variables created in VisualCron 4 may exist in your Notifications. Currently, VisualCron interprets those variables, but the support for those variables will be withdrawn for two reasons; 1 - the less flexibility in those variables and 2 - for performance reasons. Support for those variables will be withdrawn during the end of this year (2006) so please replace those with newer variables.
It is not possible to use a variable as argument
You can not enter a variable in another variables argument.
