RICOH ProcessDirector symbol notation

Symbol syntax

In RICOH ProcessDirector, this is the basic syntax of a symbol, which you can use in symbol formulas:

Name is a database property name in RICOH ProcessDirector or a parameter that is passed with the job. RICOH ProcessDirector evaluates parameters that are passed with a job through a control file such as a rules file that parses JCL parameters and values. Name can also be a method in RICOH ProcessDirector, such as getFileName, getAbsoluteFileName, getControlFileName, or getChildFileName. The Name value is case-sensitive.

Examples

${Get*Method}

This symbol causes RICOH ProcessDirector to call an internal method and return an evaluated value. To see how RICOH ProcessDirector can use this type of symbol, see the RunExternalProgram step in the Prepare phase of the PDF workflow. The RunExternalProgram step specifies this External Command property:

• Windows: copy ${getControlFileName()} C:\aiw\aiw1\samples\${Job.ID}.info.csv

The ${getControlFileName()} symbol instructs RICOH ProcessDirector to copy the external control file template into the tmp subdirectory of the spool directory and resolve any symbols that the control file contains.

The RunExternalProgram step in the Prepare phase of the PDF workflow specifies this External control file template property:

• Windows: C:\aiw\aiw1\control_files\external_programs\job_info.cfg

When RICOH ProcessDirector creates the job that uses the workflow and sets its initial property values, it uses the value that the getControlFileName method returned to resolve the external command to this:

• Windows: copy C:\aiw\aiw1\spool\default\10000003\tmp\job_info.control.text C:\aiw\aiw1\samples\10000003.info.csv

${Job.PropertyName}

This symbol causes RICOH ProcessDirector to query its database for the value of a specific RICOH ProcessDirector job property.

To see how RICOH ProcessDirector can use this type of symbol, review the contents of the job_info.cfg control file template. This control file template is in C:\aiw\aiw1\control_files\external_programs .

When RICOH ProcessDirector creates a control file from this template, it resolves the values for the ${Job.ID}, ${Job.Name}, ${Job.JobType}, ${Job.SubmitTime}, ${Job.RequestedPrinter}, ${Job.InputFile.Size}, ${Job.JobSize}, ${Job.TotalPages}, and ${Job.TotalSheets} symbols to the actual RICOH ProcessDirector job properties. For example:

${Job.ID}=10000001
${Job.Name}=Demo.pdf
${Job.JobType}=PDF
${Job.SubmitTime}=10:02.35
${Job.RequestedPrinter}=Sample
${Job.InputFile.Size}=2608549
${Job.JobSize}=26
${Job.TotalPages}=26
${Job.TotalSheets}=26

Note:
• You can also use any of the system properties in a symbol formula that RICOH ProcessDirector evaluates. For example, ${WorkflowSystem.Transform.Server.Address}.

${Math}

This symbol causes RICOH ProcessDirector to add, subtract, multiply, or calculate the modulus of two values which can be job properties or numbers. It can also generate a random number in a specified range.

The syntax of this symbol is:

${Math(value1,operator,value2)}

• value1 and value2 are job properties in symbolic notation (such as ${Job.CurrentTime}) or numbers. Numbers can contain fractional values, such as 2.45, if the property using the symbol formula supports floating point values.
• operator is +, -, *, or mod for addition, subtraction, multiplication, and modulus respectively.

For example, to add 5 minutes to the current time and store it in the Job.Info.Attr2 property, use ${Math(${Job.CurrentTime}, +, 5)}.

Only properties that use integer, numeric, or timestamp values can be used in the value fields in this formula. Only properties that support symbol notation values can be set using this formula.

If either value is a timestamp property, the only operators supported are + and -, and the other value must be an integer. The units of the integer value are minutes.

Some properties appear to have timestamp values (such as Job.TimeSubmitted) but are defined as strings, so they cannot be used as values in a Math symbol. The Math symbol can be entered in fields on step templates in the Workflow Builder, including the AssignJobValues step template, and in fields in job property notebooks.

For modulus, value1 must be an integer which is 0 or greater and value2 must be an integer which is 1 or greater.

For random number generation, the syntax of this symbol is:

• ${Math(rand, value1, value2)}

For example, to generate a random number from 1 through 10, use ${Math(rand, 1, 10)}.

Note:
• value1 and value2 are job properties in symbolic notation (such as ${Job.Copies}) or numbers.
• value1 and value2 must be integers which are zero or greater.
• The result returned is an integer between value1 and value2, inclusive.
• The random numbers that are generated are not cryptographically random.

${RulesFileParameter}

This symbol causes RICOH ProcessDirector to query a parameter file that accompanies an input file. It queries for a parameter value that is specific to another program or product.

For example, when the LPDPDF input device receives an input file, it uses the receive_lpd_pdf_jobtype.cfg control file to parse parameters that accompany the input file.

The receive_lpd_pdf_jobtype.cfg control file is located in this directory:

• Windows: C:\aiw\aiw1\control_files\rules

A receive_lpd_pdf_jobtype.cfg control file might contain this information:

orighost=mywindowshost
origuser=annsmith
origname=TestPDF.pdf

The symbols for these parameter values are:

${ORIGHOST}
${ORIGUSER}
${ORIGNAME}

To see how RICOH ProcessDirector can use this type of symbol, review the receive_lpd_pdf_jobtype.cfg file in this directory:

• Windows: C:\AIW\AIW1\samples\rules

Note:
• See Syntax for RICOH ProcessDirector control files for more detailed information about this implementation.

Usage notes for symbol formulas

These usage restrictions apply to using RICOH ProcessDirector symbol formulas:

Supported objects

RICOH ProcessDirector supports the use of symbol formulas only to set the values of job properties. You cannot use symbol formulas to set property values for any other object type, such as an input device or a printer. The symbol formula that RICOH ProcessDirector evaluates to set the value can be another job property, a primary server property, or a method call, such as: ${Job.InputFile}, ${Printer.Model}, and ${getControlFileName()}. However, a given symbol formula cannot contain both a job property and a system property or a method call at the same time.

Note:
• Changing the value of a system property might affect many symbol formulas for job properties. Because RICOH ProcessDirector updates all the symbol formulas at once, the operation can take a long time to complete.

Excluded properties

RICOH ProcessDirector does not support setting the value of the Job.Class property with a symbol formula.

Appearance in the RICOH ProcessDirector user interface

You can specify symbol formulas in workflows and in step templates through the Administration page of the RICOH ProcessDirector interface.

When viewing the property notebooks for these objects, symbol formulas always display in their formula format, such as ${Job.InputFile} as the value for the Job name property. In the properties notebook for a job that uses a workflow with steps that specify symbol formulas, the affected job properties display their evaluated values from the formulas. For example, the value of the Job name property is the actual name of the input file, such as reports.pdf.

Multiple levels of formulas

The evaluation of formulas can extend to a group of related formulas. For example:

• Job.Name=${Job.Description}
• Job.Description=${Job.CustomerName}
• Job.CustomerName=${Job.Locations}

In this case, when the Job.Locations job property has a value, RICOH ProcessDirector sets the value of the Job.CustomerName property. This, in turn, lets RICOH ProcessDirector set the value of the Job.Description property, and then set the value of the Job.Name property.

Circular formulas

A circular formula is one in which a property receives a value from a symbol formula, and then is used to provide a value for another related property. For example:

• Job.Name=${Job.Description}
• Job.Description=${Job.CustomerName}
• Job.CustomerName=${Job.Name}

RICOH ProcessDirector does not support this usage and issues an error message.

Maximum depth for multiple levels of formulas

In the multiple levels of formulas example, the formula depth is three. RICOH ProcessDirector supports a depth of up to 99 related formulas. It issues an error message if it encounters a formula depth that is greater than 99.

Use of positional properties in symbol formulas to set values for non-positional job properties

Positional properties are properties than can appear in multiple phases and steps and that might have different values in each place. For example, an administrator could configure a workflow so that the Valid return codes job property on the RunExternalProgram step appears in multiple phases and steps in the workflow and has a different value each time. The phase and step names are the names of sections on the job property notebook with the individual property names and values for each instance shown in its own section. RICOH ProcessDirector does not let you use positional properties in symbol formulas that set values for non-positional properties because there is no mechanism to specify which occurrence of the positional property to use.

Use of positional properties in symbol formulas to set values for other positional job properties

Positional properties can use symbol formulas that specify other positional properties. RICOH ProcessDirector looks for the value of the positional property that it evaluates in the symbol formula in the same phase and step that the requesting positional property specifies.

Precedence of property values set by symbol formulas

When multiple methods that specify a value for the same property exist, RICOH ProcessDirector always uses the value that the symbol formula specifies. When a symbol formula exists for a property value, RICOH ProcessDirector does this:

• Discards any value specified in a control file.

  For example, assume that the workflow specifies ${Job.InputFile} as the value of the Job name property and a control file, such as C:\aiw\aiw1\control_files\rules\receive_lpd_pdf_jobtype.cfg, specifies: DEFINE ${Job.Name} AS "${ORIGHOST}".

  RICOH ProcessDirector sets the value of the Job name property to the name of the input file for the job, not to the value that the ORIGHOST parameter for the job specifies.

• Discards any explicitly specified value in the job properties notebook for a job property that the workflow defaults with a symbol formula. You must delete the symbol formula from the workflow and process the job again to use an explicitly specified value.

Validation of symbol formulas

RICOH ProcessDirector validates the syntax and the content of the symbol formula and issues messages for error conditions. For example, both of these would result in errors: Job.Description=${Job.CustomerName and Job.Description=${Job.XYZ} The first example is a syntax error with no closing brace and the second example is an unknown job property name.