Parameter Validation with Constraints

When you configure a parameter in the Parameters tab of the Process Definition editing pop-up window, you can add constraints in the Detail View.

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: 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.

• Simple: You can use simple constraints in your Process and Chain Definitions.

There are different types of simple constraints:

• List: A list of valid values. For example: A,B,C,D,E.

• Pair List: A list of valid values with descriptions. For example: 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: A Java object that has a collection of constants. 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: For more information, see REL Expressions.
• Table: A list of values retrieved from a table. For more information, see Table Constraints.
• Query Filter: A list of values retrieved with a filter, such as a Process Monitor Filter. For more information, see Query Filter Constraints.

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.

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, but enable the user to specify a different value or leave the parameter empty.

Parameter Evaluation and Constraints

During the life cycle of a process, constraints fire a number of times to confirm the validity of the parameter value. The constraints fire for each status change except the following:

• A change to a final status (Completed, Error, Unknown, Canceled, or Killed).
• Changes to the following statuses:
  • Killing
  • Canceling
  • PostRunning
  • Disabled
  • Modified

Constraints also fire when fields or parameter values are changed. However, changes to the following 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" (LOVs), such as Oracle Applications and SAP-related Process Definitions. You can use LOVs to prevent typos. 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 number of values displayed in the LOV and not increase it.

Simple Constraints

All simple constraint types allow the use of variables.

• ${value}|value: The value of the parameter (either the default value or the value specified at submission). Use value in the Simple Constraint Data field and ${value} in the Simple Constraint Message field.
• ${legalValues}: A short list of legal values. This variable is empty when used in expression constraints.
• ${parameter}: The description of a parameter if any. Otherwise, the parameter's name.

REL Expressions

Like the List constraint, the Expression constraint consists of a Redwood Expression Language expression. The result of the expression is used to validate the value. You can use expressions both in the Simple Constraint Data field and the Simple Constraint Message field.

In the Simple Constraint Message field, you can use values such as this: The value ${value} you specified is invalid for parameter ${parameter}.

In the Simple Constraint Data field, use the keyword value for the actual value. The following example forces the value to be a number between 5 and 10: =value >= 5 && value <= 10

The following example forces the value to be either 4 or 5: = value === 4 || value === 5

You can also use special constraint functions such as the following. For more information, see Simple Constraint Data Expression Examples.

• Constraint.listConstraint(titles, list, bool)
• Constraint.pairListConstraint(titles, list, bool)
• PLSQL.constraint( 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 the Process Server is a JDBC or Oracle Job 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 optional binds 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".

Note that the column we retrieve in the Boolean expression, Translation, 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.

Warning: This example is only for illustration purposes. It is bad practice to store values in a constraint expression, especially if the values can be found in a RunMyJobs 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 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), and you must have a credential for the user specified in the connect_string (scott 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 Constraints

Unlike the other simple constraints, the Table constraint lets you specify a list of values once, then use that list in multiple Process Definitions. The list of values can be maintained from one central location.

The Table constraint requires you to populate 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 are 31, 33, 49, and 502.

Query Filter Constraints

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 submission. 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 sample 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 (for example) be used to retrieve a JobDefinition object via its business key.

{
  // 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> -- for example, JobDefinition:GLOBAL.System_Info or EventDefinition:GLOBAL.DataLoadComplete.

See Also

• Privileges Required to Use QueryFilters
• Redwood Expression Language Functions