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.
Install the external program and, if applicable, the application/secondary server software before you start this procedure.

Important points to remember when you install the base product or application/secondary servers and the other application:

  • When you install the RICOH ProcessDirector software on a Linux or AIX system, the installation program creates the RICOH ProcessDirector system user (aiw1 is the default). When you verify the operation of an external program that runs on a Linux or AIX system, use the RICOH ProcessDirector system user to do your verification testing.
  • RICOH ProcessDirector does not automatically create a system user account for RICOH ProcessDirector on a Windows application server. The installation program prompts for the name of the user account to use as the RICOH ProcessDirector user. Verify the operation of the external program from the user account for the RICOH ProcessDirector user on the Windows application server.
  • When the RICOH ProcessDirector primary computer is a Linux or AIX system, make sure that the RICOH ProcessDirector system user and the user that the other application uses have the appropriate permissions for the directories and file systems that they use.
  • If the RICOH ProcessDirector primary computer is a Windows system and the other application is on a mapped network drive, edit the mountDrives.bat file to map the network drive whenever RICOH ProcessDirector starts. The file is located in the c:\aiw\aiw1\bin\ directory.
  • Make sure that the RICOH ProcessDirector system user on a Linux or AIX primary computer or RICOH ProcessDirector on a Windows primary computer can find and execute the other application. Use one of these methods:
    • Include the full path to the application in the command that you create.
    • Add the application to the PATH environment variable for the Windows primary computer or the RICOH ProcessDirector system user on a Linux or AIX primary computer.

      This option works best if the other application runs on the same system as the primary server. If the application runs on an application/secondary server, this option only works if you mount the directory that the other application is installed in.

    • On a Linux or AIX primary computer, create a symbolic link to the other application, storing the link in /aiw/aiw1/bin.

      Storing a symbolic link in that directory provides some important benefits. RICOH ProcessDirector adds that directory to the PATH environment variable when it creates the RICOH ProcessDirector system user, so the application can be recognized without separately editing the PATH. The directory is not deleted when you apply service, although some of the files in it might be updated. The link file should not be affected.

      In addition, application and secondary servers can access this directory. As a result, they can also use the symbolic link to locate the external application if it is located within the /aiw file system. The external application cannot run on both a Linux or AIX primary computer and a Windows application server.

To set up the external program:

  1. Use the documentation for the external program and verify that it runs without errors as a standalone program.
  2. If you plan to use RunExternalProgram:
    1. If the application runs on a Linux or AIX computer, log in as the RICOH ProcessDirector system user. If it runs on a Windows computer, log in as an administrator.
    2. Compose the command that you can use to invoke the program from the command line and use it to submit an input file to the program.
      Record the command that works correctly so you can use it as the model when you configure your step template.
    3. Create a control file template for the step to use.

      If the external program reads the property values that it requires from a parameter file that accompanies the print file, the RunExternalProgram step can build that file. To generate the file, the step uses a control file template. To create the control file template:

      1. Make a copy of a parameter file that the application can use.
      2. Replace all of the property values in the file with the RICOH ProcessDirector symbol notation representation of the property. If the value is the file name for a file in the job, replace it with the appropriate RICOH ProcessDirector method call to determine the file name.

        During processing, the step uses the template to build the parameter file by resolving all the references and filling in the values for the current job.

      3. Copy the control file template into a directory in the RICOH ProcessDirector shared file system (/aiw/aiw1/ (AIX and Linux) or C:\aiw\aiw1\ (Windows).)

        Sample control file templates for external programs are installed in /aiw/aiw1/samples/external_programs/ (AIX and Linux) or C:\aiw\aiw1\samples\external_programs\ (Windows). You can copy these files to the /aiw/aiw1/control_files/external_programs/ (AIX and Linux) or C:\aiw\aiw1\control_files\external_programs\ (Windows) directory and customize them, or add your own control files to the /aiw/aiw1/control_files/external_programs/ (AIX and Linux) or C:\aiw\aiw1\control_files\external_programs\ (Windows) directory. Note the directory location of your control file template.

      4. On a Linux or AIX system, verify that the file permissions for the control file template provide access for the other class of system users. For example, set the permissions for the control file template to 666.
      5. Make sure one external command passes the control file in the parameter it expects (the -o option for including additional job properties, for example).

    4. On a Linux or AIX system, create a symbolic link to the application on the primary computer:
      1. Log on to the system that the RICOH ProcessDirector base product runs on as the RICOH ProcessDirector system user.
      2. Use the stopaiw command to stop the primary server.
      3. Use this command to create the symbolic link: 
        ln -s application_file /aiw/aiw1/bin/link_file
        Replace application_file with the full path to the executable file for the application, and replace link_file with the name of the symbolic link file you want to create. The executable file must be located within the /aiw file system.
      4. Use the startaiw command to start the primary server.
  3. If you plan to use RunHotFolderApplication:
    1. Log on to the primary computer. On AIX or Linux systems, log in as the RICOH ProcessDirector system user.
    2. Copy or transfer a sample print file into the input folder for the application.
    3. Check the other application to make sure that it starts to process the file.
    4. Monitor the output folder for the resulting file. When it arrives, copy or transfer it to another directory, then verify that it is correct.
    5. Navigate to the directory that holds the log files for the other application and make sure that you can open and view the log files.

Related information:

Sample control file templates for external programs
Parent topic: Adding functions to workflows