Setting up step templates for external steps that use the command line or control files

This is the actual command and any command-line parameters that RICOH ProcessDirector issues to run the external program. The command string can include RICOH ProcessDirector symbol notation:

• In this example, the Linux cp command only copies the JobNumber.print.pdf file from the spool directory for the job when the source file is newer than the destination file:
  cp -u ${getAbsoluteFileName(print, pdf, read)} /tmp/jobarchives
  Note:
  • ${getAbsoluteFileName(print, pdf, read)} is the RICOH ProcessDirector symbol formula that returns the name of the PDF print file in the spool directory. If the PDF print file does not exist in the spool directory when the external program runs, an error occurs.
• In this example, the external program myprogram reads the JobNumber.print.pdf file from the spool directory and writes an updated version of the file to the spool directory using redirection:
  myprogram -i ${getFileName(print, pdf, read)} > ${getFileName(print, pdf, write)}
  Note:
  • ${getFileName(print, pdf, read)} is the RICOH ProcessDirector symbol formula that returns the name of the PDF print file in the spool directory. If the PDF print file does not exist in the spool directory when the external program runs, RICOH ProcessDirector returns the name of the input file for the job, which is JobNumber.print.unknown. If that file does not exist in the spool directory, an error occurs.
• In this example, the external program auditstatistics reads the JobNumber.overrides.text file from the spool directory and writes a new statistics file JobNumber.statistics.text to the spool directory:
  auditstatistics inputfile=${getFileName(overrides, text, read)} outputfile=${getFileName(statistics, text, write)}
• In this example, the external program line2afp uses a separate parameter file for which a corresponding RICOH ProcessDirector control file exists if the AFP Support feature is installed. The control file specifies a RICOH ProcessDirector method that instructs the external program to write its output to the spool directory:
  line2afp parmdd=${getControlFileName()}
  Note:
  • ${getControlFileName()} is the RICOH ProcessDirector symbol formula that returns the name of the resolved control file. RICOH ProcessDirector generates the control file from the control file template that you specify.
  • The control file can use the getChildFileName method to return the name of a child file so that the external program can write a file to the children subdirectory in the spool directory. The external program must write the file names of child-job files in this format:
    JobNumber.UsageType.DataType.n,Job.JobType=WorkflowName
    WorkflowName is the name of the workflow that the child job requires. The workflow must exist and it must be enabled.
  • When you add a step based on the RunExternalProgram step template to a workflow, the properties that show [Receive] in the job defaults change to reflect the actual phase to which you add the step.
• In this example, the external step uses the Windows copy command to write a copy of the JobNumber.print.pdf file from the spool directory to an archive directory on the Windows system:
  copy ${getAbsoluteFileName(print,pdf,read)} d:\archive\pdf
  Note:
  • The Windows system must have either the base product or an application server installed. The application server must be connected to the primary server.
  • Specify the Windows directory by using the native Windows format for the directory name.
  • Use native Windows commands instead of SFU commands where appropriate; for example, use the copy command instead of the cp command. Not all SFU commands are available on Windows systems.
  • Depending on the command, a directory on the Windows system might not need to exist. The command can create the directory on the Windows system.
  • Make sure that you tune the step template to only run on a Windows application server. Because of the different formats for directory names on Linux and AIX, a step based on this step template will fail if RICOH ProcessDirector tries to run the step on a non-Windows system.

In this context, a valid return code is any return code from the external program that does not require a user action. Separate multiple return-code numbers with commas. For any return code from the external program that the value for this property does not include, RICOH ProcessDirector moves the job to the error state. It also issues a message in the log for the job to alert you to a problem that the external program reported.

For example, if the value of the valid-return-codes property is 0,4, and the external program finishes with a return code of 16, RICOH ProcessDirector issues a message similar to this:

AIWI6073E External step cp /aiw/aiw1/spool/default/10000016/10000016.print.unknown /archive/directory finished with a return code of 16, which is a defined as an error.