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.
  • Make sure that the RICOH ProcessDirector system user 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 RICOH ProcessDirector system user.

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

    • 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. Log on to the computer that the application runs on as the RICOH ProcessDirector system user or as the Windows user ID that the application server runs under.
    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/.)In that location, all servers that are connected to the primary server can access the file.

        Sample control file templates for external programs are installed in /aiw/aiw1/samples/external_programs/. You can copy these files to the /aiw/aiw1/control_files/external_programs/ directory and customize them, or add your own control files to the /aiw/aiw1/control_files/external_programs/ 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 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.

Other topics in this section:

Setting up step templates for external steps
Setting up workflows for external steps
Testing external step processing through RICOH ProcessDirector

Related information:

Sample control file templates for external programs
Parent topic: External steps