Adding functions to workflows

RICOH ProcessDirector workflows can be configured to send print jobs to other applications for additional processing and then receive them back into the system. The other applications can run on the server that holds the primary server, on a secondary server, or on an application server.

If your application provides processing that can be incorporated into print workflows (such as address cleansing or impositioning), you can create steps that send the print job from RICOH ProcessDirector to your application, wait for the application to finish, and then continue processing in RICOH ProcessDirector. The RICOH ProcessDirector documentation calls these steps external steps.

In a conditional workflow, external steps can receive input from multiple steps and run different programs based on the input. In the PDFProduction sample workflow, the external step receives different properties based on a job’s page count. External steps can write results to multiple places and send output to multiple steps. For example, an external step can send jobs to three different steps based on a value computed by an external program. An external step can terminate a branch of a conditional workflow.

These step templates for external steps are included with RICOH ProcessDirector:

  • RunExternalProgram

    Submits the print job to an external program using a command line interface.

  • RunHotFolderApplication

    Puts the print job in a hot folder that another application monitors. That application picks up the print job, processes it according to its configuration settings, and puts it into an output folder. RICOH ProcessDirector monitors that output folder and retrieves the job when it is ready.

Choosing which step template to use depends primarily on how the external application can accept jobs. If the application has a command line interface, the workflow can include RunExternalProgram; if the application monitors hot folders for input, the workflow can include RunHotFolderApplication. If the application has both interfaces, you can decide which step to use.

RICOH ProcessDirector provides optional features that integrate with external programs. These features include additional step templates that you can use:

  • Quadient Inspire Connect

    • ComposePDF

      Uses Quadient Inspire Designer to generate a new PDF file from a WFD file and one or more raw data files. The step waits for the new file to be returned.

    • ComposeAFP

      Uses Quadient Inspire Designer to generate a new AFP file from a WFD file and one or more raw data files. The step waits for the new file to be returned. ComposeAFP is only available when the Quadient Inspire Connect and AFP Support features are installed.

  • MarcomCentral Connect

    • ApplyXSLTransform

      Converts information in MarcomCentral format to RICOH ProcessDirector job properties.

    • CallSOAPService

      Calls the MarcomCentral Job Tickets web service and retrieves the job tickets for each order.

    • CreateJobsFromXML

      Uses the information returned by the MarcomCentral web service to create a job for each job ticket. The step submits the jobs to the MarcomProcessJobTicket workflow.

  • Pitstop Connect

    • RunPitStopOnJob

      Submits a PDF print job to PitStop Server along with an action list or PDF profile. Ricoh ProcessDirector waits for PitStop Server to process and return the job so it can move to the next step in the workflow.

  • Postal Enablement

    • SetPostalJobProps

      Lets you set job properties needed by postal software to determine how to process the mail piece information contained within the external document properties file.

    • BuildExternalDocPropsFile

      Lets you extract document data from the document properties file and create a file with the document data and headings that you need to send to an external program. The file you create is called an external document properties file.

    • MapExternalResultsFiletoDocProps

      Maps document properties that you select from an external results file to the document properties included in a modified results file. The external results file is produced by an external program.

    • UpdateDocPropsFromExternalResultsFile

      Merges the properties in the modified results file into the document properties file for the job.

  • Ultimate Impostrip® Connect

    • RunImpostripOnJob

      Submits a PDF print job to the Ultimate Impostrip® input hot folder that is set up to perform the appropriate impositioning functions on the job. RICOH ProcessDirector waits for the Ultimate Impostrip® server to return the updated job, then continues processing with the next step in the workflow.

Consider these points when deciding which step to use:

  • RunExternalProgram
    • Requires you to write a command and specify all of the necessary options. If you are not familiar with writing commands or do not have the syntax of the command to run the application, this step might be more difficult to configure.
      Note: All output that external programs write to stdout and stderror appears in the RICOH ProcessDirector job log. If your command runs a program or system command that writes all its output to stdout, we recommend that you use a script to call the external program so you can redirect the output to a different location.
    • Lets you specify the code page and language to be sent to the other application.
    • Lets you specify the return codes that the program can provide without sending the print job into an error state.
    • Lets you use a control file that contains processing parameters that the external application can use, if the program can accept one.
  • RunHotFolderApplication
    • Lets you send one or more files to the other application.
    • Requires you to configure the sending and retrieval folders correctly. The sending folder and retrieval folder can be the same one, if the file name of the file to send does not match the retrieval pattern. The Retrieval pattern is a pattern-matching string used to identify a returned job.

      For example, if the external application converts files from PostScript to PDF, the retrieval pattern could look for a file with the extension .PDF. The step can copy printfile.ps into the directory and not mistake it for the converted file, because it is looking for printfile.PDF.

      However, if you use the hot folder to send a PDF file to a preflight application, that application sends back another PDF file, most likely with the same name. In that case, the sending and retrieving folders must be different locations.

    • Does not provide the option to specify valid return codes.

      If the external application returns the expected file, the step picks up the file and moves the process to the next step without checking for errors. As a result, the other application should be configured so it does not copy a file with errors to the output directory. If the hot folder is set to time out, the job eventually goes into an error state and the issue can be resolved; if the hot folder is configured to wait indefinitely, the job continues to wait until an operator intervenes.

In some environments, the steps can be configured to work together. For example, if you want to use FTP or SCP to transfer the input file to the other program, you can create a step based on RunExternalProgram to transfer the files. Then, you can add a step based on RunHotFolderApplication, leaving the Sending folder property blank. The step does not send any files to an outgoing hot folder, but it polls the retrieving folder for the resulting file.

Processing flow: RunExternalProgram

Steps based on the RunExternalProgram step template can access files in the spool directory for a job. When an input device creates a job from an input file, it also creates a unique spool directory for the job. The spool directory contains a copy of the input file and other files that provide information about the job. External steps can call programs that update existing files in the spool directory and write new files to the directory.

When you create a step based on the RunExternalProgram step template, you can include values for these properties:

  • External command
  • External control file template
  • External program code page
  • External program language
  • Valid return codes

The next figure shows how the RunExternalProgramStep step processes a job. The step resolves methods and symbols in the command, creates a control file if needed, runs the command, receives a return code when the other program finishes processing, and updates job properties if the program sends an overrides file back. Then the job moves to the next step.

RunExternalStep step template processing

This figure shows how the RunExternalProgramStep step processes a job. The step resolves methods and symbols in the command, creates a control file if needed, runs the command, receives a return code when the other program finishes processing, and updates job properties, if the programs sends an overrides file back. Then the job moves to the next step.

When a job enters the RunExternalProgram step, the step tries to run the command provided in the External command property. If any part of the command is written in RICOH ProcessDirector symbol notation, the step resolves all references before it issues the command:

  • The command must contain two file names: the input file name (the file that the other program picks up) and the output file name (the file that the other program returns to RICOH ProcessDirector). The step must generate these names using the RICOH ProcessDirector method getFileName(). Instead of using actual file names in the command, the method is used as a symbol for the file names.

    For example, the input file name might be represented by the symbol: ${getFileName(print,pdf,read)} and the output file name might be represented by the symbol: ${getFileName(print,pdf,write)}. Using this method ensures that the application can find and return the files correctly.

  • The command can include symbols for RICOH ProcessDirector properties; if it does, those property values are entered into the command.

    For example, if the other application needs to know the job name, you can include the symbol: ${Job.Name}. The step finds the value of the Job name property and includes it in the command.

  • The application might accept property values in a parameter or control file.

    If it does, the command should include the getControlFileName() method to create a name for the control file. The step uses the control file template listed in the External control file template property to build the contents of the control file, then inserts the file name in the command.

  • The application might accept values in a JDF job ticket.

    If it does, the command should include the getFileName() method to generate the name of the JDF job ticket. An example of this syntax is ${getFileName(overrides,jdf,read)}.

After all of the symbols have been resolved, the command runs.

The external application does its processing, copies its output files to the correct locations, and returns a return code. The output files can include:

  • The modified print file, named based on the value of the getFileName() symbol that was included in the command
  • A file used to pass property values back into RICOH ProcessDirector

    RICOH ProcessDirector that can accept property values from external programs in these ways:

    • In a file named jobid.overrides.txt or .text, which contains a list of RICOH ProcessDirector attribute/value pairs
    • In an empty file with a file name that includes the attribute/value pairs, which is created in the spool file location if the file contains property value pairs on the output parameter of the command

The step compares the return code to the values listed in the Valid return codes property for the step. If it matches one of the codes, processing continues; if it does not match, the job goes into an error state.

The step looks for the file that carries the property values. If it finds a file, it reads the file (or file name) and updates the property values. Then the step completes its processing. It might pass the job to another step or terminate a branch of the workflow.

Processing flow: RunHotFolderApplication

When you create this step, you can include values for these properties:

  • File size verification count
  • File to send
  • Poll interval
  • Retrieval folder
  • Retrieval pattern
  • Retrieved file
  • Sending folder
  • Timeout interval

The next figure shows how the RunHotFolderApplication step processes a job. The step resolves the method and symbol for the name of the file to send, copies the file into the sending location, then waits as the external program processes the file. The step monitors the retrieving location for the file and retrieves the file when it has been fully copied into the location. Then the job moves to the next step.

The step can process jobs that have a single file or multiple files.

RunHotFolderApplication step template processing

This figure shows how the RunHotFolderApplication step processes a job. It resolves the method and symbol for the name of the file to send, copies the file into the sending location, then waits as the external program processes the file. The step monitors the retrieving location for the file, and retrieves the file when it has been fully copied into the location. Then the job moves to the next step.

When a job enters the step, the step resolves the value of the File to send property and locates that file in the spool directory. The step copies the print file into the location specified in the Sending folder property. The step expects the other application to pick the file up from that location.

After the file is copied, the step starts to monitor the directory listed in the Retrieval folder property. The step looks in the folder for a file whose name matches the pattern specified in the Retrieval pattern directory. If no file that meets the criteria is present, the step waits for the amount of time specified in the Polling interval property and checks again.

The step continues to check for the file for a given period of time. This length of time is determined by the value of the Timeout interval property. The timeout interval is calculated from the time the print file is copied into the Sending folder. If the modified file does not appear in the Retrieval folder before the timeout interval elapses, the job goes into an error state.

When the step finds the expected file in the directory for the first time, it notes the size of the file, but does nothing else. The step must make sure that the entire file has been transferred from the other application before it continues processing. After the polling interval has elapsed, the step checks again, finds the file, and compares the file size to the previous size.

  • If the file is larger than the previous size, the step continues to wait and checks the size again after the polling interval has elapsed.
  • If the file is the same size as it was on the previous check, the step notes that the file size has not changed; the size has been the same two times.

    The step looks at the value of the File size verification count. This value is the number of times that the file size must remain the same before the step can consider the file fully copied. If the file size verification count is equal to the number of times the file size has been the same, the step considers the file complete.

When the file is complete, the step renames the file based on the value of the Retrieved file property and copies it back into the spool directory for the job. Then the step completes its processing. It might pass the job to another step or terminate a branch of the workflow.

Note: RICOH ProcessDirector offers separately priced features that provide interfaces with specific external programs. These include Avanti Slingshot Connect, Quadient Inspire Connect, PitStop Connect, and Ultimate Impostrip® Connect. Postal Enablement works with more than one external program.
  • Avanti Slingshot Connect provides an interface with the Avanti Slingshot Management Information System.
  • PitStop Connect provides an interface with Enfocus PitStop Server 10 or higher.
  • Postal Enablement provides an interface with postal cleansing software such as Bell and Howell BCC Mail Manager and TEC Mailing Solutions MailPreparer.
  • Quadient Inspire Connect provides an interface with Quadient Inspire Designer, version 8 and higher.
  • Ultimate Impostrip® Connect provides an interface with Ultimate Impostrip® Automation or Scalable on Windows.

RICOH ProcessDirector does not supply the external program software with these features.

In this section:

  1. Setting up external programs
    Before you start the configuration tasks for an external step, you need to set up the external program that the external step calls.
  2. External steps
  3. Setting up step templates for external steps
    You create a step template that contains the command that calls the external program. Then, you tune the step template so that it will run on the Linux or Windows system on which the external program is installed.
  4. Setting up workflows for external steps
    After you create a step template to call an external program and tune the step template to run on the server that the external program is installed on, you add a step that is based on the step template to a workflow. You then assign the workflow to an input device, or use another method to assign the workflow to specific jobs.
Parent topic: Integrating with Other Applications