Custom Configuration

Many of the custom components developed will require some level of configuration, whether it be file system paths or anything else. The Scheduler system supports
standard .NET configuration files for all component types to allow for maximum flexibility and ease of conversion for organizations with a large legacy task bank.
The system also offers a custom configuration API that is integrated into the administration website. Using the custom configuration classes provided, developers
can simplify the work that needs to be done to set and maintain these values.

A custom configuration is nothing more than an object in .NET that defines the properties that are necessary for the component being developed. For example, imagine
the need to write the hilariously trivial task of printing a name to the log and the current date. Perhaps the task can take as input the name to print as well as a
format string for the date. The configuration object would look like this:

As expected, the object contains string properties that are consistent with the data that the task requires knowledge of in order to execute properly.

In the current version, only scalar types and enumerations are supported as properties. There is no support for collection types such as arrays, ArrayList,
or List<T>. Also, nested objects are currently not supported and should be flattened.

Data Annotations

The administration website has built in UI and basic validation support for these configuration objects defined using various attributes defined in the
System.ComponentModel.DataAnnotations namespace. Building on the earlier example, the name parameter is vital to execution of the task being developed. If no name
exists, the entire purpose of the task is lost. If no format string is provided for the date, the default format string can be used without an issue. Also, the
name parameter will need to be at least 2 characters in length but no more than 10 characters. Adding some validation, the configuration object may look like this:

The Required attribute indicates to the system that the parameter must be specified. The RegularExpression attribute allows the specification of a
pattern that the data must adhere to. The website configuration screens will enforce these rule when the this configuration is being applied. Properties defined on
classes used as configuration objects can often be cryptic to non-developers.

In the example, showing the user an input for something called "DateFormat" may not make much sense to the user that will be attempting to enter a value to satisfy
the purpose. The Display attribute can be used to specify additional information that will be used by the system when the configuration screen is
rendered for users to input values. Modifying our example further, we have a configuration that looks like this:

The following parameters of the DisplayAttribute class are currently supported:

Supported DisplayAttribute Properties

Name

Specifies a friendly name for the property being displayed. This name will be displayed as the label for the input on the screen.

Description

Gives more detailed information about the purpose of the data being collected. This will display as a tooltip visible when hovering over the field on
the screen.

Order

Allows specification of the order that the parameter will be displayed on the screen.

Group

For configurations with properties that can be logically grouped, specifying this property will display all parameters with the same group value in a logical
grouped area of the screen.

The illustration below shows what the definition configuration screen of the administration website would look like for the example parameters object thus far.
Note that both properties are enabled and that there is no error if the name value is left blank. This might seem strange given that the name property is required,
but it is because the value can be specified both in the configuration of the definition and later when scheduling the task that uses this configuration. By default,
the system will only ensure required values are entered when configuring the task as that is the last possible point of definition before the task runs. It is
possible to specify that the properties to be required when configuring the definition level and this will be demonstrated in the next example.

Basic configuration shown in the Administration Website.

For comparison, here is a screenshot of the scheduled task configuration screen. Note that the Name field label has an asterisk to denote that it is required and
that the field shows an error condition and message for when the property is required and must be entered:

Required configuration parameter validation.

Remember that the regular expression validation on the Name field specifies that values must be between 2 and 10 characters in length. If we only enter a
name that is one character, the system will fail validation:

Configuration parameter format validation.

Configuration Locations

Configuration of a component in the administration website can be done when adding a component definition to the system and when scheduling a task. The
Taskmatics.Scheduler.Core.ParameterAttribute attribute can be used to decorate properties of a custom configuration object to define at which levels the property
is allowed to be set. If no ParameterAttribute is applied to a property, it will be modifiable both on the definition and scheduled task configuration
screens. Looking back at the example, assume that the name of the user to be printed by the task can be specified at any time but the date format string will only
be modifiable when defining the task. In this case, the configuration object would look as follows:

The ParameterAttribute attribute takes in a value for Taskmatics.Scheduler.Core.ConfigurationLocations. The values that can be specified are:

ConfigurationLocations Values

Anywhere

The parameter value can be set at both the task and job level. This is the default value if no setting is specified.

Definition

The parameter value can only be set when defining a task. Parameters with this setting will appear read only when configuring a job.

Schedule

The parameter value can only be set when defining a job. Parameters with this setting will appear read only when configuring a task.

Nowhere

Currently treated as everywhere, this has no effect in the current version.

One important statement to make about configuration locations is the idea of value inheritance. If a property of a configuration object is defined as
Anywhere, a value can be entered for that property when configuring a task component in the system. When the
task is then assigned from the job creation wizard, the value that was set in the task configuration will be the default value shown. This value
can then be changed by the user and the system will merge all non-modified definition level parameter values with the job level override values to provide
the complete configuration for that object.

This feature enables developers to have default values that serve the majority of configurations of a component while still allowing changes for occasional scenarios
where the value is different without the need to create a new task component to achieve the same objective.

The following is a screenshot showing the task Definition screen. As expected, both fields are editable from this screen:

Task configuration showing both parameters as editable.

Constrast this with the job creation wizard screen and notice that the Format for Date field is no longer enabled (grayed out). This value cannot be
set at this level, as defined by the ConfigurationLocations value specified on the property.

Job creation wizard screen with disabled date format parameter.

Linking to A Component

Once a configuration object has been defined, it can be linked to a component by using the Taskmatics.Scheduler.Core.InputParametersAttribute or
Taskmatics.Scheduler.Core.OutputParametersAttribute attributes and specifying the type of the object that corresponds to the configuration.
Our configuration from above was for a task that would print out a name and then format the current date to the specified format string, so the full task
implementation would look like this:

In the example above, by decorating the task implementation with the InputParametersAttribute class and specifying the type of the configuration object the system
will store and provide the object to the Task in the Context property. InputParameters can be accessed the same way on classes that derive from
Taskmatics.Scheduler.Core.Triggerand Taskmatics.Scheduler.Core.EventListener as well.

The OutputParametersAttribute class is currently used to decorate classes that derive from Taskmatics.Scheduler.Core.Trigger in the event that there is custom
information that the developer wishes to pass as output from the trigger to the task as input. A custom class that is used as an output parameter configuration
object does not get rendered or configured in the administration website and is solely for providing a strongly typed configuration model for arguments passed
to a task from a trigger when the trigger is fired. A detailed example of how to specify an output configuration can be seen in the
Trigger section.