Process Definitions: Parameters Tab

Parameters are used to store values that are used by a Process Definition or Chain Definition. Parameters can have default values, which can be changed when you submit the process. In a Chain Definition, parameters can also be shared and updated between Chain Processes.

The Properties tab includes the following controls.

  • Name: The parameter name is used to refer to the parameter in the Source field and in Chain Definitions. Use only alphanumeric characters and the underscore _.
  • Direction:
    • In: You supply the value in the Process Definition or the Submit Wizard, and the value does not change.
    • Out: RunMyJobs determines the value at runtime, possibly as the result of an of operation or calculation.
    • In/Out: You can supply the value in the Process Definition or the Submit Wizard, and RunMyJobs potentially changes it at runtime as the result of an operation or calculation.
  • Type: The data type of the parameter.
    • Character: A single character.
    • Number: Only digits.
    • Date Time Zone: A date and time with a time zone.
    • Date Time: A date and time.
    • Date: A date.
    • Time: A time.
    • String: One or more alphanumeric characters.
    • File: Lets you attach files to the process in the Submit Wizard. Can contain either a file path or a FileParameter object.
      • JobFile:<process_ID>:<file_name>: JobFile expression by process ID. For example: JobFile:1234:stdout.log.
      • RelativeFile:<relative_process>:<file_name>: Relative JobFile expression. For example: RelativeFile:Initialization Step, Job 2:stdout.log.
      • doc:/<document_path>: Document path, where <document_path> is doc:partition:/<application_path>/<document_name>.<document_extension>, and <application_path> is <partition>.<application>[/<partition>.<application>]*. For example: doc:MyPartition:/MyTest.pdf or doc:MyPartition:/MyPartition2.MyApplication/MyTest.pdf.
      • Document:<partition>.[<application_bkpath>.]<document_name>: The Business Key of a document. For example, Document:MyPartition.MYFILE for a document without an assigned Application, or Document:MyPartition.MyPartition2%2e;MyApplication%2;$2.MYFILE for a document named MYFILE in Application MyPartition2.MyApplication.
    • Table: Can contain either inline XML data, a reference to a process file, or a table. Supported by RedwoodScript-based Definition Types only. The syntax is as follows:
      • Inline:<xml>: Here, <xml> represents raw XML data. The XML declaration is optional, but if you include it, there must be appropriate whitespace between it and the body of the content.
      • JobFile:<process_ID>:<file_name>: JobFile expression using process ID. For example: JobFile:1234:stdout.log.
      • RelativeFile:<relative_process>:<file_name>: Relative JobFile expression. For example: Initialization Step, Job 2:stdout.log.
      • Table:<partition>.<name>: Business key of a table. For example: Table:MyPartition.Variables.
  • Default Expression: Either a literal default value or a REL expression such as =Time.now('Europe/Berlin'). Parameters of type File cannot have a default value. For more information, see REL and Implicit Objects.
  • Description: This value is used as descriptive text in the user interface and while submitting. In the editing user interface, you can switch between Name and Description.
  • Group Name: This value lets you assign a parameter to a parameter group. Each parameter group displays as a tab in the Submit Wizard. Parameter groups are ordered by the lowest Display Order of a parameter in the group. For more information, see Parameter Group Ordering.
  • Documentation: This value is used to provide further information regarding the parameter. It is not displayed in the Submit Wizard.
  • Length: The maximum length of the parameter in characters.
  • Process Format: The format of the parameter value. You can use a specific syntax to format the value of your parameter, depending on its Type. For more information, see Parameter Formats.
  • Array: An array containing multiple values. In RedwoodScript Process Definitions, for example, you can access them like regular Java arrays. Note that array parameters are not supported by all Definition Types.
    • Array length Min: Minimum number of values.
    • Array length Max: Maximum number of values.
    • Array Options:
      • Duplicate values allowed: Allows array to contain duplicate values.
      • Sorted: Sorts array values numerically or alphabetically.
  • Editable: Lets you control whether the value can be edited in the Submit Wizard.
  • Simple Constraint Type: Constraints let you enforce rules for parameter values. For more information, see Parameter Validation with Constraints.
    • 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: Lets you enforce the constraint or allow it to be overridden.
    • Simple Constraint Sort: Lets you sort entries in the constraint's list of values. Specify Ascending, Descending, or None.
  • Parameter Options
    • Optional: Allows the parameter to be null.
    • Display: When checked, this option displays the parameter in the Submit Wizard Parameters and Summary tabs and in the Process Monitor Detail View.
    • Part Of Key: Used with Keep Clauses. At least one Process Definition parameter must be marked as Part Of Key. If you use this option, the system will keep track of how many Processes have that key Parameter set to a particular value. For example, assume you have a Process Definition with a parameter named P_COMPANY_ID set Part of Key. Also assume that the Keep Clause for the Process Definition is set to one per key. If you execute this Process Definition twice with the value of P_COMPANY_ID is set to 25 both times, the first Process will be deleted when the second finishes executing. For more information, see Retention Tab.
    • Runtime: Lets you designate a parameter as a runtime parameter.
    • Password: Lets you hide the entered value.
  • Job Definition Parameter Sub Type: For internal use only.

Note: File parameters created in versions prior to 9.0.20 contain the full path to the uploaded file. Upgrading from such versions does not change existing parameters. Any new parameters created will contain the FileParameter object.

Runtime Parameters

If an In and In/Out runtime parameter is a runtime parameter, its Default Expression (if any) will be evaluated when the process reaches status Dispatched (that is, immediately before the process reaches status Running).

Non-runtime parameters are evaluated in the Submit Wizard, once each, in the order in which they display in the Parameters tab. Runtime parameters are also evaluated once each in the order in which they display, but they are not evaluated until immediately before the process, Chain, or Chain Process reaches status Running. This is important if you create dependencies between parameters. A parameter value that references another parameter must be evaluated after all its referenced parameters. Only Runtime parameters can reference other Runtime parameters.

Parameter Group Ordering

The groups are ordered by the Display Order of the parameters, only the lowest Display Order of a group is taken into account.

Example:

Group A

  • Parameter1: Display Order 9.
  • Parameter2: Display Order 8.
  • Parameter3: Display Order 1.

Group B

  • Parameter4: Display Order 7.
  • Parameter5: Display Order 6.
  • Parameter6: Display Order 2.

Group C

  • Parameter7: Display Order 5.
  • Parameter8: Display Order 4.
  • Parameter9: Display Order 3.

The groups will be ordered by the parameters with the lowest Display Order in each group, like so:

  1. Group A

  2. Group B

  3. Group C

REL and Implicit Objects

The Default Expression field accepts REL expressions. The table below lists implicit objects that can be used within your REL expressions. For a full list of REL functionsm see Redwood Expression Language.

Implicit objects Description Class
parameters.<name> The value of parameter <name> in the current process. java.lang.String, java.lang.Number, java.util.Date, com.redwood.scheduler.api.date.DateTimeZone
outParameters.<name> The value of Out parameter <name> in the current process. java.lang.String, java.lang.Number, java.util.Date, com.redwood.scheduler.api.date.DateTimeZone
chainParameters.<name> The value of parameter <name> in the innermost Chain. java.lang.String, java.lang.Number, java.util.Date, com.redwood.scheduler.api.date.DateTimeZone
chainOutParameters.<name> The value of Out parameter <name> in the innermost Chain. java.lang.String, java.lang.Number, java.util.Date, com.redwood.scheduler.api.date.DateTimeZone
JobChainParameters.getOutValueString(<jobName>, <parameter>) The value of the Out parameter <parameter> in the Chain Process. java.util.String
JobChainParameters.getOutValueNumber(<jobName>, <parameter>) The value of the Out parameter <parameter> of the Chain Process. java.lang.Number
JobChainParameters.getOutValueDate(<jobName>, <parameter>) The value of the Out parameter <parameter> of the Chain Process. java.util.Date
chainJobId The ID of the innermost Chain. Must be a Runtime parameter. long
jobId The ID of the current process. Must be a Runtime parameter. long
topLevelJobId The ID of highest parent in hierarchy. Must be a Runtime parameter. long
returnCode The return code of the current process. long
stepIterations The teration number of the current Step or process. long
waitEvents.<name>.finalPath The path of the file that raised the wait event <name> (after move, if applicable). java.lang.String
waitEvents.<name>.originalPath The path of the file that raised the wait event <name> (before move, if applicable). java.lang.String
waitEvents.<name>.raiserComment The comment on the raiser of the wait event <name>. java.lang.String
waitEvents.<name>.raiserJobId The ID of the process that raised the wait event <name> (if applicable). java.lang.Long

Parameter Evaluation Order

Assume that a Process Definition has two parameters, param1 and param2. The data type of param1 is Number and its Default Expression is set to 1. The parameter param2 is also a Number parameter, but its Default Expression is set to =parameters.param1 * 2.

Here, the Display Order is very important. If parameter param2 has a lower Display Order than param1, it will be displayed first. However, RunMyJobs will not be able to resolve it, and attempting to submit the process will result in an exception being thrown. This is due to the fact that param1, which is part of the Default Expression of param2, has not yet been evaluated when RunMyJobs attempts to evaluate param2.