bbc Adobe Central Output Server Version 5.5 Managing Your Print Process with Adobe Output Manager 5.0
2003 Adobe Systems Incorporated. All rights reserved. As of April 12, 2002, Accelio Corporation (formerly JetForm Corporation) was purchased by Adobe Systems Incorporated. As of that date, any reference to JetForm or Accelio shall be deemed to refer to Adobe Systems Incorporated. Adobe Central Output Server 5.5, Managing Your Print Process with Adobe Output Manager 5.0 for Microsoft Windows and UNIX May 2003 If this guide is distributed with software that includes an end user agreement, this guide, as well as the software described in it, is furnished under license and may be used or copied only in accordance with the terms of such license. Except as permitted by any such license, no part of this guide may be reproduced, stored in a retrieval system, or transmitted, in any form or by any means, electronic, mechanical, recording, or otherwise, without the prior written permission of Adobe Systems Incorporated. Please note that the content in this guide is protected under copyright law even if it is not distributed with software that includes an end user license agreement. The content of this guide is furnished for informational use only, is subject to change without notice, and should not be construed as a commitment by Adobe Systems Incorporated. Adobe Systems Incorporated assumes no responsibility or liability for any errors or inaccuracies that may appear in the informational content contained in this guide. Please remember that existing artwork or images that you may want to include in your project may be protected under copyright law. The unauthorized incorporation of such material into your new work could be a violation of the rights of the copyright owner. Please be sure to obtain any permission required from the copyright owner. Any references to company names in sample templates are for demonstration purposes only and are not intended to refer to any actual organization. Adobe and the Adobe logo are either registered trademarks or trademarks of Adobe Systems Incorporated in the United States and/or other countries. Microsoft and Windows are either registered trademarks or trademarks of Microsoft Corporation in the United States and/or in other countries. Quest and Vista Plus are registered trademarks of Quest Software Inc. Unix is a registered trademark of The Open Group. All other trademarks are the property of their respective owners. Adobe Systems Incorporated, 345 Park Avenue, San Jose, California 95110, USA. Notice to U.S. Government End Users. The Software and Documentation are Commercial Items, as that term is defined at 48 C.F.R. 2.101, consisting of Commercial Computer Software and Commercial Computer Software Documentation, as such terms are used in 48 C.F.R. 12.212 or 48 C.F.R. 227.7202, as applicable. Consistent with 48 C.F.R. 12.212 or 48 C.F.R. 227.7202-1 through 227.7202-4, as applicable, the Commercial Computer Software and Commercial Computer Software Documentation are being licensed to U.S. Government end users (a) only as Commercial Items and (b) with only those rights as are granted to all other end users pursuant to the terms and conditions herein. Unpublished-rights reserved under the copyright laws of the United States. Adobe Systems Incorporated, 345 Park Avenue, San Jose, CA 95110-2704, USA. For U.S. Government End Users, Adobe agrees to comply with all applicable equal opportunity laws including, if appropriate, the provisions of Executive Order 11246, as amended, Section 402 of the Vietnam Era Veterans Readjustment Assistance Act of 1974 (38 USC 4212), and Section 503 of the Rehabilitation Act of 1973, as amended, and the regulations at 41 CFR Parts 60-1 through 60-60, 60-250, and 60-741. The affirmative action clause and regulations contained in the preceding sentence shall be incorporated by reference.
Contents 1 Overview... 4 Who Should Read This Document?...4 Related Documentation...4 Printing with Output Manager...5 Using Output Manager for Print Management Only...5 Using Output Manager for Both Document Creation and Print Management...6 2 Installing and Configuring... 8 Installing Central...8 Installing Output Manager...8 Starting Output Manager...9 Configuring the Device...11 Using Output Manager to Manage Printing Only...12 Configuring Central...12 Using Output Manager to Manage Both Document Creation and Printing...16 Creating a Command Macro...17 Command Macro Syntax...18 Defining Rules...19 Testing and Troubleshooting the Configuration...22
1 Overview With Adobe Central Output Server (Central), you can produce professional-looking documents such as invoices, packing slips, purchase orders, and statements. But how can you actively manage the printing process for those documents? Adobe Output Manager enhances your operating system print queue capabilities, contributing to a complete document generation solution. Output Manager provides these capabilities: Print management: Output Manager centrally monitors print activity and printers on the network. Reprinting: This feature allows you to reprint jobs that have failed or been lost, without the need to resubmit and rerun the job. Print redirection: You can move print jobs from stalled or busy printers to available printers, thus resolving print process backlogs. Load balancing: This feature promotes more efficient use of printer resources by spreading print jobs over multiple printers. WHO SHOULD READ THIS DOCUMENT? If you are responsible for configuring Output Manager to work with Central, then this document is for you. You should be familiar with Central and its Agents. Depending on the integration method you choose, you may also need to understand how Output Manager uses queues and command macros to send output to its devices. RELATED DOCUMENTATION This document describes the steps necessary to integrate Output Manager with Central. For further information on managing your printing process, see the Adobe Output Manager 5.0 Administrator s Guide. You can also consult the documentation that comes with Central, such as these guides: Getting Started Working with Central Print Agent Reference
Managing Your Print Process with Output Manager Overview 5 PRINTING WITH OUTPUT MANAGER There are two ways in which you can use Output Manager, in combination with Central and the Central Agents, to manage your printing requirements. Before setting up your environment to run Output Manager, you should understand these scenarios. Use Output Manager for print management only, by using Central to create the final document and send it to Output Manager for printing. This method has several benefits: The method is easier to implement. You can use your existing Central processes and Job Management Database entries. You can take advantage of all the print management features of Output Manager. This method has one drawback: The process is inherently less managed because Output Manager does not handle document generation. Use Output Manager for both document creation and print management, by having Output Manager run the Central Agents itself. This method also has benefits: You have the added security of controlling document formatting through Output Manager. The process is inherently more managed because Output Manager handles all of the document generation. This method has one drawback: If you have an existing Central installation, you must substantially rework your environment. You must re-implement the jobs, tasks, and steps from your Job Management Database by creating the equivalent elements in Output Manager. Using Output Manager for Print Management Only In this scenario, Central generates the document and sends it to Output Manager for printing. Central accepts data into the collector directory, and determines the processing required using the Job Management Database. Central runs the necessary Agents to create the formatted document and then sends the document to Output Manager. Output Manager directs the document to the appropriate printer on the network.
Managing Your Print Process with Output Manager Overview 6 Print Management with Output Manager These steps describe a sample printing process using Output Manager to print a Central document: 1. A data file is placed in the collector directory. The data file has the command ^job CHECKS, which corresponds to a job in the Job Management Database. 2. Central executes the steps for the job CHECKS in the Job Management Database. This job consists of two steps that use the commands JFMERGE and QR. 3. For the step JFMERGE, Central launches Print Agent with the specified command line options. Print Agent merges the data file with a template and sends the final document back to Central. 4. For the step QR, Central launches the program QR.exe, which sends the final document to Output Manager. Output Manager then submits the document to the physical printer queue, and manages the printing. Using Output Manager for Both Document Creation and Print Management In this scenario, Output Manager generates and prints the document. You do not use Central, the collector directory, or the Job Management Database to run the Central Agents. Instead, Output Manager accepts data directly from the data source, and determines the processing
Managing Your Print Process with Output Manager Overview 7 required using its own job rules and steps. Output Manager then sends the data and the required command line options to the specified Agents. Finally, Output Manager directs the formatted document to the appropriate printer on the network and manages the printing. Document Creation and Print Management with Output Manager These steps describe a sample printing process using Output Manager to create and print a document: 1. A data file is placed in the Output Manager queue using any process that submits files to queues. For example, you may use a Line Print Request (LPR) command or the Output Manager QR command to place the data file in the Output Manager queue. For more about job submission, see the Output Manager 5.0 Administrator s Guide. The data file has the job name attribute CHECKS. In other words, the data file has a number of attributes or properties, one of which defines the job name. This job name attribute should not be confused with the ^job command. The job name attribute CHECKS corresponds to a rule defined for the Output Manager queue. An Output Manager rule is comparable to a job in the Job Management Database. 2. Output Manager executes the actions for the rule CHECKS. Output Manager actions are comparable to job steps in the Job Management Database. The rule CHECKS consists of two actions that use the command macros ADOBEMRG and QR. Output Manager command macros are comparable to tasks in the Job Management Database. 3. For the action ADOBEMRG, Output Manager launches Print Agent with the specified command line options. Print Agent merges the data file with a template and sends the final document back to Output Manager. 4. For the action QR, Output Manager sends the final document to the specified printer queue and manages the printing.
2 Installing and Configuring Use this checklist to complete the installation and configuration activities for Output Manager: Step Activity 1. Install Central Pro 5.5. For details, see Installing Central on page 8. 2. Install Output Manager 5.0. For details, see Installing Output Manager on page 8, Starting Output Manager on page 9, and Configuring the Device on page 11. 3. Determine if Output Manager is to manage your printing only, or if Output Manager is to manage both your document creation and your printing. If Output Manager is to manage your printing only, you will need to modify the necessary Job Management Database tables. For details, see Using Output Manager to Manage Printing Only on page 12. If Output Manager is to manage both your document creation and your printing, you will need to create the necessary job rules and steps. For details, see Using Output Manager to Manage Both Document Creation and Printing on page 16. INSTALLING CENTRAL Install Central 5.5 before you configure Output Manager. For more information, see the Getting Started guide for Central. If Output Manager will manage both your document creation and your printing, you do not need to run Central as a Service, since Output Manager runs the Agents itself. As a result, you can stop the Central Service to save processor time, unless you need the Service for processing other jobs. If Output Manager will manage only your printing, you must run Central as a Service. INSTALLING OUTPUT MANAGER Install Output Manager on the same server where you installed Central. Log on as a Windows user with administrative rights and use a valid Output Manager installation key.
Managing Your Print Process with Output Manager Installing and Configuring 9 Starting Output Manager The Output Manager window allows you to manage your queues and devices using an expandable tree structure. The window pictured here shows the default queues and devices that install with Output Manager. To start Administrative Client 1. Click Start > Programs > Output Manager 5.0 > Administrative Client. 2. Enter a user name and password. Output Manager uses the underlying security of your operating system to log users on to the application. In a network environment, any user with access to the network can log on to Output Manager using their network user name and password. The host and port are configured automatically.
Managing Your Print Process with Output Manager Installing and Configuring 10 Output Manager includes a Configuration Editor, which enables you to configure your queues and devices. To start the Configuration Editor (WinCQ) 1. Click Start > Programs > Output Manager 5.0 > Configuration Editor (WinCQ). 2. Enter a user name and password. Output Manager uses the underlying security of your operating system to log users on to the application. In a network environment, any user with access to the network can log on to Output Manager using their network user name and password.
Managing Your Print Process with Output Manager Installing and Configuring 11 Configuring the Device You need to set up a device to send output to the correct physical device, usually a network printer. To configure a device 1. In the left pane of WinCQ, select a device. For example, click HP. 2. In the Device Host Name box, type the host name. 3. In the Physical Device Name box, type the device name. 4. Click File > Upload Configuration. Warning: If you forget to upload your configuration before you leave the Job Rules Editor dialog box, the Job Rules Editor does not save your information.
Managing Your Print Process with Output Manager Installing and Configuring 12 USING OUTPUT MANAGER TO MANAGE PRINTING ONLY When Output Manager manages just your printing, document creation is handled by Central. Central calls the necessary Agents to create the formatted document and copy it to an Output Manager queue. Output Manager directs the document to the requested printer on the network and manages the printing. You must configure both Central and Output Manager before they can handle your document creation and printing requirements. To do so: Modify the Task and Job Tables of the Job Management Database to enable Central to create the formatted document and to copy it to an Output Manager queue. For details, see Configuring Central on page 12. Ensure that the required printers are known to Output Manager. For details, see Configuring the Device on page 11. Configuring Central In order to have Central create your documents and then have it interact with Output Manager for printing, you will need to make a number of updates to the tables in the Job Management Database: Update the Print Agent Task Table entry, JFMERGE. The update will direct Print Agent to output the formatted document to a temporary file, rather than to a physical printer. The temporary file will then be picked up by a custom Agent for placement in an Output Manager queue. Create a new Task Table entry, QR, for a custom Agent. This custom Agent will take the temporary file created by Print Agent and place it in an Output Manager queue. Add an additional step to the Job Table for all jobs that will have their printing managed by Output Manager. This additional step will invoke the custom Agent, QR, to place the temporary file, output by Print Agent in the previous step, into an Output Manager queue. Updating the JFMERGE Task Table Entry In order to have the Print Agent task, JFMERGE, create an output file that can be passed to the custom Agent task, QR, it is necessary to add a second -z command line option as the rightmost entry in the JFMERGE Program options. Leave the first -z command line option in place so that the @PhysicalDev parameter will get properly populated by Central.
Managing Your Print Process with Output Manager Installing and Configuring 13 The Task Table entry for JFMERGE is: With the addition of the second -z command line option, the Program options for JFMERGE will read: -l -apr"@preamblename." -all"@logfilename." -asl@skiplines -amq@managedmem -ams"@mstname." -m@macro#.@loadflag -z"@physicaldev." @PrintDirectorParms. @OtherJobTokens. aii"@inifilename." -z"jfserver.tfa" The entry -z"jfserver.tfa" will force JFMERGE to generate the printer output as file jfserver.tfa. Central will populate -z"@physicaldev." with the name of the targeted device. The targeted queue name is hard-coded in the -q option in the QR Task Table entry. Creating the QR Task Table Entry Create a custom Agent to take the output from Print Agent and copy it into an Output Manager queue. The custom Agent, in this case, is the process qr.exe, which typically resides in the c:\outmgr\bin directory. The Task Table entry for the custom Agent, QR, is:
Managing Your Print Process with Output Manager Installing and Configuring 14 The Program options for QR are: -x CHICKSIMB -q print -P @PhysicalDev. jfserver.tfa where: -x is the name of the host machine (CHICKSIMB in this example). -q is the name of the targeted queue (print in this example) -P is the name of the targeted output device. In this example, @PhysicalDev. equates to the device name as it comes into Central from the -z command line option of the ^job command. jfserver.tfa is the name of the temporary output file created by JFMERGE. Updating Job Table Entries In order to get the output from JFMERGE into an Output Manager queue, you must add a step to each job that falls into this category. The added step will invoke QR to place the temporary output file, jfserver.tfa, into a targeted queue. In this example, there is an extra step added to job name vpon.
Managing Your Print Process with Output Manager Installing and Configuring 15 The first step in this job is to call JFMERGE to merge a form and data, and to print the resulting output to a temporary file, rather than to a physical printer. The Output file value of A tells JFMERGE to print its output to a temporary file. The name of the temporary file, jfserver.tfa, is identified in the second -z command line option added to the JFMERGE Task Table Program options. (See Updating the JFMERGE Task Table Entry on page 12.)
Managing Your Print Process with Output Manager Installing and Configuring 16 The second step in this job is to call QR to take the temporary file created by JFMERGE and to copy it to the Output Manager queue named print. The name of the queue was identified in the -q option in the QR Task Table Program options. (See Creating the QR Task Table Entry on page 13.) The Input file value of A tells QR to use the output file from the previous step in performing its task. Once QR copies the file to the Output Manager queue, it is handled as any print file. USING OUTPUT MANAGER TO MANAGE BOTH DOCUMENT CREATION AND PRINTING When Output Manager both generates and prints your documents, you do not use the collector directory, the Job Management Database, or Central to run the Central Agents. Instead, Output Manager accepts data directly from the data source, determines the processing required using its own job rules and steps, and then sends the data and the required command line options directly to the Central Agents. The Central Agents create the formatted document. Output Manager directs the document to the appropriate printer on the network and manages the printing.
Managing Your Print Process with Output Manager Installing and Configuring 17 Before Output Manager can generate and print your documents, you must configure it. To do so: Create a command macro for each Central Agent that Output Manager will call. For details, see Creating a Command Macro on page 17 and Command Macro Syntax on page 18. Define rules that specify Agent processing. For details, see Defining Rules on page 19. Ensure that the required printers are known to Output Manager. For details, see Configuring the Device on page 11. Test your Output Manager setup. For details, see Testing and Troubleshooting the Configuration on page 22. Creating a Command Macro You must create a command macro for each Central Agent that you want Output Manager to run. A command macro equates to the Task Table entry that Central normally uses to run its Agents. In most cases, you will want to use Output Manager to run Print Agent. The procedure in this section describes how to create a command macro for Print Agent. Rather than using the pre-installed macro JFMERGE, create a new command macro to run Print Agent. JFMERGE was not created specifically to work with Central. Creating a new macro ensures that the macro references the correct configuration file (jfmerge.ini) and the correct executable (jfmerge.exe). To create a command macro for Print Agent 1. In the left pane of Configuration Editor (WinCQ), select a queue. 2. Click Tools > Job Rules Editor. 3. Click the Rule Actions tab. 4. Click Macros. 5. Click Add and type a macro name. For example, type ADOBEMRG. You can use any macro name except JFMERGE. 6. Click OK.
Managing Your Print Process with Output Manager Installing and Configuring 18 7. Type an explanation of the macro in the Description box and type the path of the Print Agent executable (jfmerge.exe) in the Value box. 8. Click OK twice. 9. Click File > Upload Configuration. Warning: If you forget to upload your configuration before you leave the Job Rules Editor dialog box, the Job Rules Editor does not save your information. Command Macro Syntax You use command macros to specify the command line options. Command macros, in turn, may contain variables in their definition. Variables are preceded by the $ (dollar sign) character. You can use Configuration Editor to see the definitions and values for command macros and variables. To view and evaluate command macros 1. In Configuration Editor (WinCQ), click Tools > Job Rules Editor. 2. Click the Rules Action tab. 3. Click Macros. 4. In the Macro Name list, click the macro that you want to view and evaluate.
Managing Your Print Process with Output Manager Installing and Configuring 19 5. The macro definition, including variables, appears in the Value box. Click Evaluate Macro to see the value of the macro, without variables. As an example, look at the Sample Document Bursting Template rule and its rule actions. In the Macro Name list, click QPARSE: The QPARSE macro is defined as $QMBINDIR\qparse.exe. The $QMBINDIR variable is defined as $QMDIR\bin. The $QMDIR variable is defined as c:\outmgr. With all the variables substituted, QPARSE is defined as c:\outmgr\bin\qparse.exe. The parameters for QPARSE are: -f $FILE -ft $SYS_FILETYPE -o outfile -p myprofile The $FILE variable resolves to the name of the input print stream. The $SYS_FILETYPE variable resolves to the default file type. You can review other default macros to see how you can create your own custom command macros. Defining Rules Rules specify the Agent processing for a particular data file that arrives in the queue. Rules equate to Job Management Database entries for a given job. You can define several different rule actions for a particular queue. Output Manager determines which rule to run based on the search criteria that you specify for the rule. To define the search criteria for a new rule 1. In the Job Rules Editor, click Add Rule.
Managing Your Print Process with Output Manager Installing and Configuring 20 2. Type the rule name and click OK. 3. Type an explanation of the rule in the Description box. 4. Click the Source Type tab. 5. Ensure that Job Attribute is selected in the Source Type list. The source types determine the nature of the search criteria: For Job Attribute, you define an attribute and value. For ASCII, you define a text string to search for, and column and row values to identify the string s location. For XML, you define a string to search for, and an XML attribute to search. 6. Ensure that jobname is selected in the Job Attribute Name. 7. In the Job Attribute Value box, type the name of the job. For example, type CHECKS. To define the rule actions to run Print Agent 1. Click the Rule Actions tab.
Managing Your Print Process with Output Manager Installing and Configuring 21 2. Click Add Step and click ADOBEMRG in the Command list. This is the command macro that you created to run Print Agent. 3. Type the required command line options for the ADOBEMRG step in the Parameter box. The minimum required command line options are: formfile -aiiconfigfile -zfilename.$sys_entryid $FILE where: formfile is the name and location of the template (.mdf). -aiiconfigfile specifies the name and location of the configuration file. The default configuration file path is c:\program files\adobe\central\server\jfmerge.ini. -zfilename.$sys_entryid specifies a temporary output file. $FILE is the input file. The system variables $SYS_ENTRYID and $FILE are replaced by the job identifier and the name of the data file respectively. For more on variables, see Command Macro Syntax on page 18. For more information on Print Agent command line options, see the Print Agent Reference guide.
Managing Your Print Process with Output Manager Installing and Configuring 22 4. Click Add Step and click QR in the Command list. This command macro runs the program qr.exe, which copies the output from the previous step to an output queue. 5. Type the required command line options for the QR step in the Parameter box. The minimum required command line options are: -x $SYS_QMEHOST -q print -P $RULE_DEVICE $FILE where: -x identifies the QME host. $SYS_QMEHOST is the name of the QME host that the job was originally submitted to. -q identifies the queue that the job runs from. -P identifies the device. $RULE_DEVICE is the value of the device output option in a rule. $FILE identifies the input as the output from the previous step. For more on variables, see Command Macro Syntax on page 18. 6. Click the Rule Options tab. 7. In the Output Device list, select a device name. For example, click HP. 8. Click File > Upload Configuration. Warning: If you forget to upload your configuration before you leave the Job Rules Editor dialog box, the Job Rules Editor does not save your information. Testing and Troubleshooting the Configuration The simplest way to test your Output Manager setup is to use the submit feature of Administrative Client. To test your Output Manager setup 1. In the left pane of Administrative Client, right-click a queue. 2. Click Submit. 3. Type or browse for the data file in the Spool File Name box. 4. Type the jobname in the Entry Name box. For example, type CHECKS.
Managing Your Print Process with Output Manager Installing and Configuring 23 5. You can select a device from the Printers list or let the output print to the queue s default printer. For help with troubleshooting, look at these files in the Logs\OutMgr directory: QME.log Qcapture.log jme.log Configuration information is located in the file OutMgr\db\config.ini. If an error occurs during processing, Output Manager places a file in the OutMgr\spool1 directory with the same number in the filename as the job number that experienced the error. This file gives you some useful information about the nature of the error. Agent errors are recorded in the Central logs. For more information, see the Working with Central guide.