Constraints are widely used in databases to force valid values in tables, to ensure nobody makes a typo when entering data. In Redwood Server constraints are used to validate In parameter values of parameters with directions In and InOut. The constraints have no effect on the Out value of parameters. There are two types of constraints, built-in and simple. Built-in parameters may have built-in constraints which are used to validate the In parameter value and/or display a list of valid values (LOV). You use simple constraints in your process definitions.

There are different types of simple constraints:

List - A list of valid values
Pair List - A list of valid values with descriptions
Enumeration - A Java object that has a collection of constants
Expression - An expression
Table - A list of values retrieved from a table
Query Filter - A list of values retrieved with a filter, such as filters

The Simple Constraint Data field is used to specify the list, expression, or table name. The Simple Constraint Message is displayed when the value of the parameter does not match the simple constraint. A good Simple Constraint Message could be the following:

"Please choose a valid value from the list, the value you entered is not valid."

Optional Constraints

When a parameter constraint is optional, the constraint is used but not enforced. This allows you, for example, to use a constraint to create a list of values for the user to choose from; the user does not have to choose a value and can either specify a different value (that is not in the list) or leave the parameter empty.

Parameter Evaluation and Constraints

During the life cycle of a process the constraints fire a number of times to confirm the validity of the parameter value.

The constraints fire for each status change except the following:

status change to a final state ( Completed, Error, Unknown, Canceled, Killed )
status changes to the following statuses
- Killing
- Canceling
- PostRunning
- Disabled
- Modified

Note that all constraints also fire when fields or parameter values are changed; changes to the following list of fields are ignored:

BlocksOnJob
ChildOrder
CompletionStrategy
CreationTime
CreationTimeZone
Description
JobChainCall
JobChainStep
LLPVersion
NextRecalculation
NextSubmitBaseTime
NumChildJobs
NumJobFiles
NumJobLocks
NumJobMetaData
NumJobNotes
NumJobRaiseEvents
NumJobWaitEvents
RequestedStartTimeType
StatusForJobGroup
UniqueId

Built-in Constraints

Some process definitions have built-in constraints to create 'lists of values' (LOV), such as Oracle Applications of SAP-related process definitions. An LOV is a list of valid values to choose from and prevents typo's. When you create a simple constraint on one of these parameters, your constraint must adhere to the criteria of the built-in constraint; you can restrain the amount of values displayed in the LOV and not increase it.

Simple Constraints

All simple constraint types allow the use of variables:

${value}|value - value of the parameter; the default value or the value specified at submit time. You use value in the Simple Constraint Data field and ${value} in the Simple Constraint Message field.
${legalValues} - short list of legal values (This variable is empty when used in expression constraints).
${parameter} - description of the parameter, if set, otherwise its name.

List Constraints

The List constraint is the easiest to create and parameter-specific. The following illustrates a valid List constraint with the following in the Simple Constraint Data field:

A,B,C,D,E

Pair List

Like the List constraint, the Pair list constraint is the easy to create and parameter-specific. The following illustrates a valid Pair List constraint with the following in the Simple Constraint Data field:

A="First Letter",B="Second Letter",C="Third Letter",Z="Last Letter"

Note that the letters (A, B, C, and Z) are the values passed on to the parameter. The submit wizard will create a list of values for the user to choose from.

Enumeration

The Enumeration constraint works much like the table constraint except that it uses Enumerations in the API instead of Tables. See Package com.redwood.scheduler.api.model.enumeration for a list of built-in enumerations.

Specifying JobStatus in the Simple Constraint Data field will use the com.redwood.scheduler.api.model.enumeration.JobStatus Enumeration and restrict parameter values to valid process statuses such as Completed or Scheduled.

Expression

Like the List constraint, the Expression constraint is parameter-specific and consists of a Redwood Expression Language expression. The result of the expression is used to validate the value.

An example Simple Constraint Message you can use is:

The value ${value} you specified is invalid for parameter ${parameter}.

Using Redwood Expression Language expressions:

Use the keyword value for the actual value, in the following example force the value to be a number between 5 and 10.

=value >= 5 && value <= 10

In the following example force the value to be a number, either 4 or 5.

= value === 4 || value === 5

You can also use the special constraint functions:

Constraint.listConstraint(titles, list, bool)
Constraint.pairListConstraint(titles, list, bool)
PLSQL.contraint( connect_string, query, binds)

In the above functions, the following parameters can be used:

titles is a comma separated list of titles.
list is either a normal list or a pair list
bool is a boolean expression involving the parameter value, true evaluates to accept and false to reject.
connect_string is a special connect string in the form user=<user> endpoint=<process_server>
- where process server is a JDBC or OracleJob process server
- a JDBC/OracleJob credential must exist for user <user> and endpoint <endpoint>
- example connect string: user=scott endpoint=MSLN_ORCL
query is a database query with optionally bind parameters
binds is an optional comma-separated, ordered list of bind parameters for the query (typical bind syntax)

Examples

Constraint.listConstraint()

=Constraint.listConstraint('Country', '31,33,49,502', \
Table.getColumnString('Countries', value, 'Translation') !== '')

This example works with the following table named countries:

Key	Name	Abbreviation	Translation	Conversion_Rate
31	The Netherlands	NL	Nederland	1.0
33	France	Fr	France	1.0
49	Germany	De	Deutschland	1.0
502	Guatemala	Gt	Guatemala	11.6

Note that the column we retrieve in the boolean expression, Translation in the example above, is not really relevant. The value returned is compared to '', which means empty. If the column is not mandatory and is not filled, the operator will not be able to use the value associated with the column. Note that this example is only for illustration purposes and destined to show the syntax. It is bad practice to store values in a constraint expression and even more so if the values can be found in a Redwood Server table - use the table constraint instead.

Constraint.pairListConstraint()

=Constraint.pairListConstraint('Country', 'Nederland=31,France=33,Deutschland=49,Guatemala=502', \
Table.getColumnString('Countries', value, 'Translation') !== '')

This example works with the table named Countries as well.

PLSQL.contraint()

The following examples retrieve the values from a database table or view. You must have a JDBC process server connected to the database (in these examples named MSLN_JDBC_Orcl ), a credential for the user specified in the connect_string ( scott the famous Oracle user in this example). The last example uses a bind variable that is set to the value of a parameter named Country.

=PLSQL.constraint('user=scott endpoint=MSLN_JDBC_Orcl', 'select cust_id "Customer ID" from sales')

=PLSQL.constraint('user=scott endpoint=MSLN_JDBC_Orcl', 'select cust_id "Customer ID", customer_name "Customer" from sales')

=PLSQL.constraint('user=scott endpoint=MSLN_JDBC_Orcl', 'select name "City", state "State/province" from cities where country = ?', parameter.Country)

Table

Unlike the other simple constraints, the Table constraint allows you to specify a list of values once that can be used in multiple process definitions. The list of values can be maintained from one central location. The Table constraint requires you to fill a table. You can use the built-in System_Variables table or create your own. The value used will be the value from the Key column in the table. In the example above, the values available would be 31, 33, 49, and 502.

To use a table, you select Table in the Constraint Type field and fill the name of the table in the Simple Constraint Data Field.

Query Filter

The query filter constraint allows you to use object filters to generate list of values for parameters, this is especially handy for RedwoodScript process definitions. The submitter must be able to see the object filter, or the parameter value will not be evaluated at submit-time. If the parameter is optional, this has no major consequences, however, if the parameter is mandatory, the user will not be allowed to submit the process. Object filters also display a list according to the requester's privileges, so two different users might see different lists.

In the following example RedwoodScript code, the process definition has a parameter named pFilter which has a query filter constraint on the filter All process definitions. When the process definition is submitted, you can choose a process definition for pFilter, the value is a string, which can then be used to retrieve the JobDefinition object, via its business key, for example.

{
  // Print the actual parameter value
  jcsOut.println("parameter=" + pFilter);
  // Get a business key for the parameter value
  BusinessKey key = BusinessKey.valueOf(pFilter);
  // Use the business key to retrieve the JobDefinition
  JobDefinition jDefinition = jcsSession.createBusinessKeyResolver().getJobDefinitionByKey(key);
  // Print the name of the JobDefinition
  jcsOut.println("JobDefinition=" + jDefinition.getName());
}

The value of the query filter is <object_type>:<partition>.<object_name>, such as JobDefinition:GLOBAL.System_Info or EventDefinition:GLOBAL.DataLoadComplete, for example.

Values

Field	Description	Default Value
Simple Constraint Type	The type of constraint to use.	None
Simple Constraint Data	The data to be used by the constraint (list, expression).
Simple Constraint Message	The message to display when the constraint is violated.
Simple Constraint Optional	Enforce the constraint or allow it to be overridden.	Enforced
Simple Constraint Sort	Sort entries in the constraint LOV either Ascending, Descending, or no sort.	Ascending

Product Documentation

Parameter Validation using Constraints