Working with PDF Forms and Documents. PegaRULES Process Commander 5.1

Transcription

1 Working with PDF Forms and Documents PegaRULES Process Commander 5.1

2 Copyright 2006 Pegasystems Inc., Cambridge, MA All rights reserved. This document describes products and services of Pegasystems Inc. It may contain trade secrets and proprietary information. The document and product are protected by copyright and distributed under licenses restricting their use, copying distribution, or transmittal in any form without prior written authorization of Pegasystems Inc. This document is current as of the date of publication only. Changes in the document may be made from time to time at the discretion of Pegasystems. This document remains the property of Pegasystems and must be returned to it upon request. This document does not imply any commitment to offer or deliver the products or services described. This document may include references to Pegasystems product features that have not been licensed by your company. If you have questions about whether a particular capability is included in your installation, please consult your Pegasystems service consultant. For Pegasystems trademarks and registered trademarks, all rights reserved. Other brand or product names are trademarks of their respective holders. Although Pegasystems Inc. strives for accuracy in its publications, any publication may contain inaccuracies or typographical errors. This document could contain technical inaccuracies or typographical errors. Changes are periodically added to the information herein. Pegasystems Inc. may make improvements and/or changes in the information described herein at any time. This document is the property of: Pegasystems Inc. 101 Main Street Cambridge, MA Phone: (617) Fax: (617) PegaRULES Process Commander Document: Working with PDF Forms and Documents Software Version 5.1 Updated: August 2006

3 Contents Chapter 1: Introduction... 1 Chapter 2: The SmartForms Feature... 2 Introduction... 3 The eform Rules and the eform Rules Accelerator... 3 Activities... 5 The Code-Pega-eForm Class... 7 Summary of Steps... 8 Configuring the Data Mapping... 9 Before You Begin... 9 Creating the Rules...10 Processing PDF Forms...12 Using a File Service to Provide Forms to Process...12 Using the GetEForm Activities to Provide Forms to Process...13 Extracting the Data...14 Generating PDF Forms and Flattened Documents...17 Generating a PDF Form...17 Assembling the Final Document from the Form...19 Saving the Generated PDF Forms and Flattened Documents...24 Attaching PDFs to Work Objects...24 Saving a PDF Form as a File...26 Chapter 3: Converting Word Documents to PDF Files...28 Client-Side PDF Conversion Option...29 The ActiveX Control and the Printer Driver...29 Sample Rules...31 Background PDF Conversion Option...36 PegaDISTRIBUTION MANAGER Setup...36 The Process...36 The ConvertAttachmentToPDF Activity...37

4 Chapter 1 Introduction Many organizations use Adobe Acrobat Portable Document Format (PDF) forms and documents to support business processes. PegaRULES Process Commander provides two ways to generate PDF documents: The SmartForms feature automates the processing of and creation of PDF forms, eliminating manual steps. With the SmartForms feature, Process Commander can process an incoming PDF form (a loan application, for example), automatically generating a work object and starting the flow. Additionally, Process Commander can automatically generate a PDF form and populate the fields with information from a work object, creating a document that complies with the policies of your organization. Process Commander provides a printer driver that you can use to convert Microsoft Word documents that have been attached to work objects as file attachments to flat PDF documents. You can configure this feature in either of two ways: as a background process managed by PegaDISTRIBUTION MANAGER, or, as a client-side process that runs on individual user workstations. This document describes how to use both features to process and generate the PDF correspondence you need to support the business processes you implement with your Process Commander applications. If your application must process or generate PDF forms, continue to Chapter 2. If your application must convert Word.doc files to PDF files, go to Chapter 3.

5 2 The SmartForms Feature Introduction Chapter 2 The SmartForms Feature The Process Commander SmartForms feature provides both development and runtime components. An accelerator helps during development by creating the rules that specify the destination for extracted data or the source of the data to use when generating a new PDF form. Activities that interact with a public API provide the runtime processing. They process incoming PDF forms, generate PDF forms, convert form fields to static text, merge several PDF files into one, apply encryption and document permissions to PDF files, save new PDF files, and attach PDF files to work objects.

6 Working with PDF Forms and Documents The SmartForms Feature 3 Introduction The SmartForms feature is supported by the following items: Two rule types: Rule-File-eForm and Rule-Map-eForm. eform file rules instances of Rule-File-eForm hold PDF forms that Process Commander uses as templates for new PDF forms. eform map rules instances of Rule-Map-eForm provide a data mapping for the PDF form fields, matching them to Process Commander properties. Create eform Rules Acclerator, which automates the process of creating eform file and eform map rules. Code-Pega-eForm, a helper class used to store PDF files temporarily while Process Commander is working on them. Activities that use the public API EFormUtils to manipulate PDF forms and documents. The activities provide a common interface to the API that you can use in your applications. For information about invoking the EFormUtils API directly, see the JavaDocs. Note: A PDF form has interactive form fields. After the fields in a PDF form are converted to static text (that is, flattened), the form is considered a PDF document. The eform Rules and the eform Rules Accelerator The rule types that support the SmartForms feature are Rule-File-eForm and Rule-Map-eForm. In creating a new PDF form, a Process Commander application uses the PDF form stored in an eform file rule as the template, and an eform map rule to determine which clipboard data to enter into the fields in the form. To extract data from a PDF form, the applicaton uses an eform map rule to determine into which clipboard properties to store the field data extracted from the form. Rule-File-eForm As instances of Rule-File-eForm, eform file rules store an uploaded PDF file. When Process Commander generates a PDF file, it uses the document stored in an eform file rule as a template for the generated file. While Process Commander does not use an eform file rule when extracting data from a form, having a form of that type helps you create an eform map rule during development.

7 4 The SmartForms Feature Introduction An eform file rule has a three-part key: The name of the class it belongs to that is, the applies to class. An eform file and its corresponding eform map rule must have the same applies to class. The name of the file. The file type (extension), for example, pdf Note: The PDF forms that you plan to use as templates for the documents that Process Commander generates must have a static layout. That is, the Adobe Acrobat dynamic layout feature that supports expanding tables is not supported in PegaRULES Process Commander. Rule-Map-eForm As instances of Rule-Map-eForm, eform mapping rules specify the relationship between form fields of a PDF form and properties in Process Commander. When you create an eform map rule, you specify to which eform file rule the mapping applies. An eform map creates a two-way mapping. When Process Commander extracts data from an incoming PDF form, it uses the map rule to determine into which properties to write the form values. When Process Commander generates a PDF document, it uses the map rule to determine into which form fields to write property values from the clipboard. An eform map rule has a two-part key: The name of the class it belongs to that is, the Applies To class. An eform file and its corresponding eform map rule must have the same Applies To class. The name of the map that is, the value entered in the Purpose field. When you specify the name of an eform map to one of the PDF activities, you identify it with this name. Create eform Rules Accelerator To simplify the process of creating an eform rule and its corresponding eform map rule, use the Create eform Rules Accelerator (eform Rules Accelerator). Use the accelerator to upload and parse a source PDF form. It presents the fields from the form, and you select which Process Commander properties match those fields.

8 Working with PDF Forms and Documents The SmartForms Feature 5 Activities Process Commander provides nine standard activities that you can use to manipulate PDF files. The activities do the following: Process an incoming PDF form by extracting the data and mapping it to the clipboard Generate a PDF file in the following ways: By creating a new form from a template specified in an eform file rule and populating the form fields with property values from the clipboard By merging several PDF files (forms and/or documents) into one PDF file Convert the active fields in a PDF form to static text Apply security and document permissions settings to a PDF form or document Retrieve PDF files to use when concatenating several PDF files into one PDF file Store the results in the following ways: Write the resulting PDF to a file on the server Attach a PDF file to a work object Note: A generated PDF file must be either saved or attached to a work object before you can examine it. To use these activities, you write activities that call them, typically from a flow utility or a service rule. Figure 1 lists the standard activities that support the PDF feature. The following sections describe these activities in more detail.

9 6 The SmartForms Feature Description Creates PDF forms, populating the fields with property values from the clipboard. Extracts field values from PDF form fields. Processes PDF files in three ways: Creates one PDF form or document by concatenating several PDF files Applies form flattening to convert active PDF form fields to static PDF text Applies security and document permissions restrictions to a PDF file Code-PegaeForm.ConcatenateEForms Code-PegaeForm.GetEFormFromFile Code-PegaeForm.GetEformFromRuleFileBinary Code-PegaeForm.GetEformFromRuleFileEForm Retrieves a PDF file stored as an instance of Rule-FileeForm. Code-PegaeForm.GetEFormFromURL Code-Pega-eForm.WriteEFormToFile Work-.AttachEForm Retrieves a PDF file stored in a directory on the Process Commander system. Retrieves a PDF file stored as an instance of Rule-File- Binary. Retrieves a PDF file by uploading it from a URL. Saves a PDF form or document as a file on the Process Commander server. Attaches a PDF form or document to a work object. Figure 1. Standard Activities for Manipulating PDF Forms

10 Working with PDF Forms and Documents The SmartForms Feature 7 The Code-Pega-eForm Class The Code-Pega-eForm class is a helper class for working with PDF files. Pages of class Code-Pega-eForm, sometimes called eform pages, serve as temporary storage locations for the PDF forms while they are being manipulated. As with all subclasses of the Code- base class, eform pages cannot be saved to the database. Instead, use activities to set the resulting property values into properties on Work- pages or other pages that can be saved. Figure 2 lists the properties in the Code-Pega-eForm class that are used by the PDF processing activities listed in Figure 1. Property and mode pyeform, Java Object pyeforms, Java Object List pyfieldsmapped, Single Value integer pyfilesavedto, Single Value text Description Serves as the container or holder of the PDF file, storing it a byte array of PDF data. The ExtractDataFromEForm activity finds the source file in this property. The GenerateEForm activity puts the PDF file it creates into this property. Holds a list of PDF forms or documents multiple byte arrays of PDF data that are to be merged into one PDF file by the ConcatenateEForms activity. The number of form fields that were read from a PDF form when the ExtractDataFromEForm processed a PDF form. The file name and file path of a PDF file saved by the WriteEFormToFile activity. After the activity saves the contents of the pyeform property as a file, it updates the value of this property. Figure 2. Properties in the Code-Pega-eForm Class

11 8 The SmartForms Feature Introduction Summary of Steps Following are the steps to complete when configuring a Process Commander application to handle PDF form processing or generation: 1. Plan the implementation. What is the context? For example, do you need to build a flow that creates a work object when a PDF form arrives? If so, you can design a flow that starts when a file service (Rule-Service-File) delivers the PDF. Do you need to build a flow that generates an agreement or proposal and sends it to a customer? In that case, create a flow utility and an activity that calls the GeneratePDFForm activity. 2. If the properties that map to the form fields of the PDF form to be processed or generated do not exist, create them. 3. With the printed copy of the form in hand, run the Create eform Rules Accelerator. You upload the PDF form and then specify which fields to map to which Process Commander properties. The eform Accelerator creates a Rule-File-eForm and a Rule-Map-eForm instance. 4. Create the activities that implement the desired functions and use them at the appropriate place in your application.

12 Working with PDF Forms and Documents The SmartForms Feature 9 Configuring the Data Mapping For Process Commander to generate a new PDF form, it needs a rule that specifies a PDF form to use as a template (an eform file rule) and a rule that specifies which properties to use to populate the form s fields (an eform map rule). For Process Commander to extract data from a PDF form, it needs a rule that specifies into which properties to put the extracted data (an eform map rule). The eform Rules Accelerator uses a flow to guide you through the process of creating eform file and eform map rules. The Accelerator imports and parses the PDF form you identify. Then it displays a list of all the form fields, making it easier for you to match the fields to Process Commander properties. If you create the rules, you must manually enter the name of each form field and verify that you made no data entry errors. Because the accelerator uses a flow, the data you enter is stored as a work object until you finish the flow. When you finish the flow, the eform Accelerator creates an eform file rule for the uploaded PDF form and an eform map rule that specifies how the fields in the form map to Process Commander properties. Before You Begin Before you create the eform rules, complete the following tasks: Copy the PDF form (which has one or more interactive field definitions) to your workstation. Print a copy of the PDF form. Unless you created the form yourself, the field names may not seem straightforward. Determine the names of all the interactive fields and write each field name code next to the text that represents the field on the printed copy of the form. Refer to the printed copy as a guide when you run the Accelerator. Determine the Applies To class for the new rules. Typically, this is a class that inherits from the Work- base class. Determine the names and classes of the Process Commander properties that map to the form fields. Note the following: The eform Accelerator enables you to select properties from the Applies To class only. If you need to map a form field to a property that does not belong to the Applies To class, you must edit the eform map rule after the Accelerator saves it.

13 10 The SmartForms Feature Configuring the Data Mapping When creating map rules for PDF forms that Process Commander generates, you cannot use repeating groups (properties of mode Page List) unless the same number of groups is used for each generated PDF form. The PDF form used as the template must have a static layout the Adobe Acrobat dynamic layout feature that supports expanding tables in PDF forms is not supported in the 4.2 SmartBuild release of Process Commander. Determine the RuleSet and version for the new rules. Creating the Rules Complete the following steps: 1. From the Process Commander home page, click the Integration icon. 2. On the Integration home page, under Wizards, select Create eform Rules. 3. In the eform Configuration form, enter a description of the work object that holds the configuration information while you work on the eform rules. Then click Start. 4. In the Select eform Properties form, complete the fields as shown in Figure 3. Field Applies to RuleSet Name RuleSet Version Value Select the class rule that you want the generated rules to apply to. Typically, this is a class that inherits from the Work- base class. Select the RuleSet for the generated rules. Select the version of the RuleSet. Figure 3. Fields on the Select eform Properties Form 5. In the Upload PDF File form, click the Browse button and select the PDF form. Then click Next. The Accelerator imports and parses the PDF form. It then lists the form fields present in the form. 6. In the Select eform Fields form, select the fields that you want to map, and then click Next. The Accelerator displays the constrained list of form fields in the Map eform Fields form. A selection field that lists the properties of the class you specified in the Applies to field appears next to the name of each form field.

14 Working with PDF Forms and Documents The SmartForms Feature In each of the selection list fields, select the matching Process Commander property. If you need to map a form field to a property from a class other than the Applies To class, select a property to use as a placeholder. Then, after the Accelerator creates the eform map rule, open the rule, create a page entry for the appropriate class on the Pages & Classes tab, and edit the mapping as needed. 8. In the Review and Save form, expand the sections, examine the values set in the fields, and make changes as necessary. Then click Next. 9. In the eform Configuration form, click Finish.

15 12 The SmartForms Feature Processing PDF Forms Processing PDF Forms Processing PDF forms means configuring a Process Commander application to identify and retrieve new forms, and then extract the data from them. You can configure Process Commander to identify the forms to process in several ways. To retrieve the data from a form, use the ExtractDataFromEForm activity. Before ExtractDataFromEForm can be called, however, the PDF form to process must be located in the pyeform property on a page of class Code-Pega-eForm. Typically, you configure your application so that a calling activity creates the page, puts the PDF form on the page, and then calls the ExtractDataFromEForm activity. Using a File Service to Provide Forms to Process Although it is beyond the scope of this document to describe file services, using a file service (instance of Rule-File-Service) is a logical way to identify PDF forms to process. When using a file service, a file listener monitors a directory where files in this case PDF forms are submitted. The listener routes the files to the service and the service uses a structured parse rule to process the files. To process a PDF form in this case, you would configure a structured parse rule to call the ExtractDataFromEForm activity. For example: 1. In the first step, the structured parse rule creates a named page of class Code-Pega-eForm. 2. The parse rule uses a Java step to move the PDF form to the pyeform property on the page. (The pyeform property holds a byte array of PDF data.) For example: try { java.io.inputstream is = parsestate.getinputstream(); java.io.bytearrayoutputstream baos = new java.io.bytearrayoutputstream(is.available()); byte[] buffer = new byte[4096]; int bytesread = 0; while ((bytesread = is.read(buffer, 0, 4096))!=-1) { baos.write(buffer, 0, bytesread); } baos.flush(); baos.close(); is.close(); ClipboardPage eformpage = tools.findpage("eformpage"); ClipboardProperty eform = eformpage.getproperty("pyeform");

16 Working with PDF Forms and Documents The SmartForms Feature 13 eform.setvalue(baos.tobytearray()); } catch(exception e) { olog.error("unable to read eform.", e); throw new PRRuntimeException("Unable to read eform.", e); } olog.infoforced("pdf read to clipboard successfully."); 3. Finally, the parse rule calls activity, passing it the name of the eform map rule to use and the name of the page where the PDF form is located. Using the GetEForm Activities to Provide Forms to Process Another way to retrieve the PDF forms to process is to use the four GetEForm activities. These activities retrieve a PDF and then put it in the pyeform property on a page of class Code-Pega-eForm. Depending on which activity you use, the PDF is retrieved from a URL, a file in a directory on the Process Commander server, an eform file rule (instance of Rule-File-eForm), or a binary file rules (instance of Rule-File-Binary). Before a calling activity can invoke one of the GetEForm activities, it must create a page of class Code-Pega-eForm. It then calls GetEForm activity on that step page. For example, Figure 4 shows activity steps that create a step page of class Code-Pega-eForm and call the GetEFormFromRuleFileBinary: Figure 4. Calling the GetEFormFromRuleFileBinary Activity

17 14 The SmartForms Feature Processing PDF Forms Figure 5 describes the activities that retrieve PDF files. Activity Code-Pega-eForm. eform.geteformfromfile Code-PegaeForm.GetEFormFromRuleFileBinary Code-PegaeForm.GetEformFromRuleFileEForm Code-PegaeForm.GetEFormFromURL Description Retrieves a PDF from a file in a directory on the Process Commander server and puts it in the pyeform property on the eform page. This activity has one parameter: FilePath, which specifies the absolute path to the file. Retrieves a PDF from a binary file rule (instance of Rule- File-Binary) and puts it into the pyeform property on the eform page. This activity takes the three keys to the binary rule as input parameters: AppName, FileName, and FileType. Retrieves a PDF from an eform file rule (instance of Rule-File-eForm) and puts it in the pyeform property on the eform page. This activity takes the three keys to the eform file rule as input parameters: ClassName, FileName, FileType Retrieves a PDF from a URL and puts it in the pyeform property on the eform page. This activity has one input parameter: URL, which specifies the URL of the eform. Figure 5. The GetEForm Activities Extracting the Data After a PDF form has been identified and set into the pyeform property on a page of class Code-Pega-eForm, use activity to retrieve the data from the form and set the field values into properties on the clipboard. This activity retrieves a PDF form stored in the eform property. It processes the form, using the specified eform map rule to determine into which properties to put the form data. ExtractDataFromEForm Activity Reference Before an activity can call the ExtractDataFromEForm activity, the following must be true: A named page of class Code-Pega-eForm exists on the clipboard. The PDF form is in the pyeform property on the named page.

18 Working with PDF Forms and Documents The SmartForms Feature 15 The calling activity and the eform file and eform map rule that you want to use belong to the same class, typically a work class. The ExtractDataFromEForm activity has two input parameters, described in Figure 6. Parameter SourceEFormPage MapPurpose Description The name of the page of class Code-Pega-eForm where the PDF form to be processed is located. The key to the eform map rule. An eform map rule has two keys: the Applies To class and the Purpose name. The MapPurpose property supplies the second key, the Purpose name. The Applies To class is the class of the calling activity s primary page. SkipValidation???? Figure 6. Input Parameters for ExtractDataFromEForm When called, the ExtractDataFromEForm activity does the following: 1. Retrieves the PDF form from the pyeform property on the eform page specified by the SourceEFormPage parameter. 2. Uses the MapPurpose parameter to identify and then retrieve the appropriate eform mapping rule. 3. Writes the field values to the appropriate properties according to the eform mapping rule. Using the ExtractDataFromEForm Activity As with the other PDF processing activities, you use them by calling them from other activities. The calling activity must set the context first by locating the PDF form to process, and putting the form in the pyeform property on a page of class Code-Pega-eForm. Then the calling activity calls activity, passing it the name of the page where the PDF form is located and the name of the eform map rule to use. For example: 1. The calling activity creates a page of class Code-Pega-eForm. 2. The calling activity then calls the GetEFormFromURL activity on that page. 3. The GetEFormFromURL retrieves a PDF form from the specified URL and puts it into the pyeform property on the page and returns control to the calling activity.

19 16 The SmartForms Feature Processing PDF Forms 4. The calling activity calls ExtractDataFromEForm, passing in the name of the page where the PDF is located and the name of the eform map rule to use. 5. The ExtractDataFromEForm activity processes the PDF form, writes the field values to clipboard properties according to the map rule, and then returns control to the calling activity. 6. The calling activity continues. For example, assume that the ExtractDataFromEForm activity mapped the field values into a work page so now the calling activity validates the data, creates an ID, and saves the work object.

20 Working with PDF Forms and Documents The SmartForms Feature 17 Generating PDF Forms and Flattened Documents To generate PDF forms and then convert them to PDF documents, use and Code-Pega-eForm.ConcatenateEForms activities. GenerateEForm creates a new PDF form and populates the fields with values from clipboard properties. ConcatenateEForms completes further assembly and final processing. It can merge the newly created PDF form (built from customer-specific data by the GenerateEForm activity) with static, boilerplate text into a final document. This activity can also apply to the form encryption, document permissions, and field flattening. Field flattening converts the PDF form into a static PDF document. Generating a PDF Form activity creates a new PDF document, merging data from the clipboard into a PDF form template. The PDF form template is the uploaded file stored in an eform file rule. GenerateEForm Activity Reference Before an activity can call activity, the following must be true: A named page of class Code-Pega-eForm must be in the clipboard so the GenerateEForm activity has a place to store the form. The calling activity and the eform file and eform map rule that you want to use belong to the same class. The GenerateEForm activity has three input parameters as described in Figure 7. Parameter MapPurpose TargetEFormPage Description The key to the eform map rule to use. An eform map rule has two keys: the Applies to class and the Purpose name. The MapPurpose property supplies the second key, the Purpose name. The primary key is the Applies To class of the calling activity s primary page. The name of the page of class Code-Pega-eForm on which to store the results. This page must already exist.

21 18 The SmartForms Feature Generating PDF Forms and Flattened Documents Parameter SourceEFormPage Description (Optional) The name of a page of class Code-Pega-eForm that holds a previously generated PDF form that is still on the clipboard and that you want to update. Figure 7. Input Parameters for GenerateEForm The GenerateEForm activity can create a new PDF form or update a previously generated PDF form that is still on the clipboard and has not been saved. When called, the GenerateEForm activity does the following: 1. Retrieves the specified eform map rule. 2. Does one of the following: If a value is provided for the SourceEFormPage parameter, locates the PDF form stored in the pyeform property on that page. If a value is not provided for the SourceEFormPage parameter, identifies the eform file rule specified by the map rule. The PDF form stored in the rule becomes the template for the new PDF form. 3. Generates the PDF form in one of the following ways: If a value is provided for the SourceEFormPage parameter, it updates the PDF form stored in the page s pyeform property with the property values according to the specified eform map rule. If a value is not provided for the SourceEFormPage parameter, it populates the form fields of the template PDF form with clipboard property values according to the specified eform map rule. 4. Puts the new PDF form in the pyeform property on the page specified by the TargetEForm parameter. Using the GenerateEForm Activity To use activity, call it from another activity. The calling activity sets the context first by creating a page of class Code-PegaeForm so the GenerateEFormActivity has a place to put the form that it creates. Then the calling activity calls activity, passing it the name of the page where the PDF form is be stored and the name of the eform map rule to use. For example: 1. An activity creates a page of class Code-Pega-eForm. 2. The activity calls activity, passing it the name of the eform map rule to use and the name of the page on which to store the results.

22 Working with PDF Forms and Documents The SmartForms Feature The GenerateEForm activity creates the PDF form and stores it into the pyeform property on the page. 4. The calling activity continues. Assume that it calls either the AttachEForm activity to attach the PDF form to a work object or the WriteEFormToFile activity to save it as a file. Note: When using as a template a PDF form that was generated by Adobe Designer, there are times when the generated PDF document does not show the property values that were written to its fields. The work around for this issue is to configure your activity to call the ConcatenateEForms activity directly after running the GenerateEForm activity. That is, the activity should call GenerateEForms and then ConcatenateEForms before calling AttachEForm or WriteEFormToFile. Assembling the Final Document from the Form The Code-Pega-eForm.ConcatenateEForms activity provides the following main functions: Merge several PDF files into one. For example, an application might create loan agreements or proposals, parts of which are boilerplate material (copyright information, liability statement, and so on). You can store the static information in separate PDF files. Then, use this activity to merge the static information with a form created by the GenerateEForm activity from customer-specific information into one proposal or letter. Convert a PDF form with active form fields to a static PDF text. Apply security settings and document permissions to a PDF form or document. When using the ConcatenateEForms activity to merge documents, use the GetEForms activities described on page 13 to retrieve the documents to merge. ConcatenateEForms Activity Reference Before an activity can call the Code-Pega-eForm.ConcatenateEForms activity, the following must be true: A named page of class Code-Pega-eForm exists and has the PDF documents you want concatenated stored in the pyeforms property on that page. The pyeforms property holds a list of byte arrays of PDF data. Note that this can be a list of one. That is, if your goal is to apply encryption or field flattening to a single PDF form, that PDF form must be located in the pyeforms property, not the pyeform property.

23 20 The SmartForms Feature Generating PDF Forms and Flattened Documents The PDF documents are listed in the pyeforms property in the order in which you want them concatenated. The source PDF documents are not encrypted and do not have any security settings applied to them. The Code-Pega-eForm.ConcatenateEForms activity has six input parameters as described in Figure 8. Parameter PerformFieldFlattening PerformDocumentEncryption DocumentPermissions UserPassword MasterPassword Description (Optional) Specifies whether you want the form fields to be converted from active fields to a static area that is part of the PDF document like the other text and images in the document. (Optional) Specifies whether you want the document to be encrypted. (Optional) Specifies the numeric code that represents the document permissions for the PDF file. For example: AllowAssembly = 1024 AllowCopy = 16 AllowDegradedPrinting = 4 AllowFillIn = 256 AllowModifyContents = 8 AllowModifyAnnotations = 32 AllowPrinting = 2052 AllowScreenReaders = 512 If you do not specify a value for this parameter, there is no security on the resulting PDF file. To combine the values of more than document permission code into a single integer for this parameter, use a bitwise OR statement. For String.valueOf( ) ) For a complete list of permission value codes, see the itext JavaDocs description of the itext PDFWriter Java class at (Optional) The document's user password; that is, the password that gives a user the document permissions specified. (Optional) The document's owner password; that is, the password that gives a user full access to the PDF.

24 Working with PDF Forms and Documents The SmartForms Feature 21 Parameter Use128Encryption Description (Optional) Process Commander supports both 40-bit and 128-bit encryption. This parameter specifies whether or not to use 128-bit encryption. The value in this parameter applies only if the PerformDocumentEncryption parameter is set to true. If PerformDocumentEncryption is set to true, but Use128Encryption is not, Process Commander uses 40-bit encryption. Figure 8. Input Parameters for ConcatenateEForms When called, the ConcatenateEForms activity does the following: 1. Retrieves the PDF file or files stored in the pyeforms property on the page of class Code-Pega-eForm. 2. Determines which PDF configuration parameters are specified by input parameters. 3. Merges the documents into a single document, concatenating them in the order in which they were listed in the pyeforms property, and applies the PDF configuration parameters as specified: If field flattening is set to true, converts the active form fields to static PDF text. If document permissions and encryption parameters are specified, applies them as specified. Using the ConcatenateEForms Activity To use the Code-Pega-eForm.ConcatenateEForms activity, call it from another activity. The calling activity sets the context first by obtaining the PDF file or files you want to process and putting them in the pyeforms property on a page of class Code-Pega-eForm. Then the calling activity calls the ConcatenateEForms activity on that step page, passing it the appropriate PDF configuration parameters. For example: 1. An activity creates a page of class Code-Pega-eForm and then calls activity. 2. The GenerateEForm activity creates the PDF form and stores it in the pyeform property on the page. 3. The calling activity creates another page of class Code-Pega-eForm. Note that if the goal for using the ConcatenateEForms activity is to process only the PDF form that the GenerateEForm activity generated, the calling activity would skip steps 3 through 6 of this procedure.

25 22 The SmartForms Feature Generating PDF Forms and Flattened Documents 4. With the new page as the step page, the activity calls one of the GetEForm activities, passing it the parameter values it needs to identify and retrieve the PDF form or document. 5. The GetEForm activity retrieves the PDF form or document and stores it in the pyeform property on the new page. 6. The calling activity repeats steps 3 through 5, as necessary to retrieve all the PDF files. Each retrieved PDF file is stored on a separate page of class Code-Pega-eForm. 7. When all the PDF files are retrieved (or the one PDF form is generated), the calling activity creates another page of class Code-Pega-eForm to hold the final (concatenated) document. 8. With the page meant for the final document as the step page, the calling activity uses the Property-Set method to copy the individual PDF files from their pages to the pyeforms property on the step page, in the order they are to be concatenated. For example, in Figure 9 the Property-Set method moves PDF files from pages (of class Code-Pega-eForm) named copyrightpage, statementpage, and quotepage into the pyeforms property on a page (of class Code-PegaeForm) named composite. Figure 9. Setting PDF Files into the pyeforms Property 9. With the page for the final PDF as the step page, the calling activity calls the ConcatenateEForms activity passing in values for input parameters as appropriate. For example, in Figure 10, the activity specifies that the form fields in the final document are to be converted to static text, the document must be encrypted, and user password is user, and so on.

26 Working with PDF Forms and Documents The SmartForms Feature 23 Figure 10. Activity Step That Calls the ConcatenateEForms Activity 10. The ConcatenateEForms activity creates the final PDF document, applies document permissions (if any), and stores it in the pyeform property on the page of class Code-Pega-eForm specified for the final PDF file. 11. The calling activity continues. Assume that it attaches the PDF to a work object or saves it to a file.

27 24 The SmartForms Feature Saving the Generated PDF Forms and Flattened Documents Saving the Generated PDF Forms and Flattened Documents You can configure a Process Commander application to save the PDF forms and PDF documents it generates as a file to the Process Commander server or as a file attachment for a work object. Attaching PDFs to Work Objects To save a generated PDF as a file attachment for a work object that is, as an instance of Data-WorkAttach-File use the Work-.AttachEForm activity. AttachEForm Activity Reference Before an activity can call the Work-.AttachEForm, the following must be true: The work object must exist and a work page must be on the clipboard A named page of class Code-Pega-eForm is on the clipboard and the PDF form or document you want to attach is in the pyeform property on that page. The AttachEForm activity has nine input parameters as described in Figure 11. Parameter PageName InsHandle Filename eformpage pynote pycategory actioncalledfrom Screen Description The name of the work object page, typically pyworkpage. The work object ID: the value of the work object s pzinskey property. The name to use for the file. The name of the eform page (page of class Code-Pega-eForm) that contains the PDF file to attach to the work object A value for the pynote property. Typically, a brief description of the file attachment. (Optional) The name of the attachment category under which the file is listed in the History and Attachments window for the work object. If you do not specify a category, the file is listed under the category Other Files. (Optional) If the activity is called by a flow action, the name of the flow action. Leave this parameter blank.

28 Working with PDF Forms and Documents The SmartForms Feature 25 Parameter SuppressHTML Description The AttachEForm activity generates a stream of HTML and stores the HTML on the activity thread page unless you set this parameter to true. If the AttachEForm activity is called without user interaction, set this parameter to true. If the activity is called from a flow action, for example, set this parameter to false. Figure 11. Input Parameters for the AttachEForm Activity When called, the AttachEForm activity does the following: 1. Retrieves the PDF file from the pyeform property on the specified page. 2. Creates a page for the file attachment, a page of class Data-WorkAttach- File. 3. Obtains the work object ID from the work page and sets it to the file attachment page. 4. Encodes the PDF to Base64 and puts it in the pyattachstream property on the file attachment page. 5. Copies the value of the FileName input parameter to the pxattachname property on the file attachment page. 6. Copies the value of the InsHandle input parameter to the pxrefobjectkey property on the file attachment page. 7. Saves the PDF file as a file attachment, creating a link between the work object and the attachment. Using the AttachEForm Activity To use the Work-.AttachEForm activity, call it from another activity. The calling activity must first set the context by obtaining the PDF form or document to be saved as the file attachment. For example: 1. At the appropriate point during a work object s lifecycle, an activity creates a page of class Code-Pega-eForm and calls the GenerateEForm activity. 2. The GenerateEForm activity creates a PDF form, stores the form in the pyeform property on the page, and then returns control to the calling activity. 3. The calling activity creates a new page of class Code-Pega-eForm, sets the pyeforms property on that page with the PDF form, and calls the

29 26 The SmartForms Feature Saving the Generated PDF Forms and Flattened Documents ConcatenateEForm activity to flatten the fields and apply security to the document. 4. The calling activity now calls AttachEForm activity, passing it values for the work page, the source page where the PDF is located, the name to use for the file attachment, and so on. 5. The AttachEForm activity saves the PDF form as a file attachment associated with the work object and returns control to the calling activity. 6. The calling activity uses a post-condition to determine whether the file attachment succeeded. 7. The calling activity returns control to the flow. Note: The AttachEForm activity saves the file attachment to the work object but does not commit the work object to the database. The flow commits the work object. If you are experimenting with the SmartForms feature and you use the AttachEForm activity outside of a flow, the calling activity must commit the work object (using the Commit activity method) before you can examine the file attachment. Saving a PDF Form as a File To save a PDF form or flattened PDF document as a file on the Process Commander server, use the Code-Pega-eForm.WriteEFormToFile activity. WriteEFormTo File Activity Reference Before an activity can call the Code-Pega-eForm.WriteEFormToFile activity, the following must be true: A named page of class Code-Pega-eForm is on the clipboard and the PDF form or document you want to save is in the pyeform property on that page. The directory you want to save the file to exists and Process Commander has write privileges for that directory. This activity has one input parameter: Filepath. Filepath specifies the file name for and path to the file, including its extension. If you use a relative path for the location of the file, the path starts in the Process Commander temp directory. To determine the location of the temp directory, examine the pxprocess page in the Clipboard Viewer. The pxtemppath property on the pxprocess page specifies the location of this directory.

30 Working with PDF Forms and Documents The SmartForms Feature 27 Using the WriteEFormToFile Activity To use the Code-Pega-eForm.WriteEFormToFile activity, you call it from another activity. The calling activity must first set the context by obtaining the PDF form or document to save. For example: 1. An activity creates a page of class Code-Pega-eForm and calls the GenerateEForm activity. 2. The GenerateEForm activity creates a PDF form and stores it in the pyeform property on the page. 3. The calling activity continues. With the page of class Code-Pega-eForm as the step page, the activity calls the WriteEFormToFile activity, passing in a value for the Filepath parameter. 4. The WriteEFormToFile activity saves the PDF file to the directory specified, using the file name specified in the Filepath parameter. 5. The calling activity uses a post-condition to determine whether the file was successfully saved. 6. The calling activity continues.

31 28 Converting Word Documents Saving the Generated PDF Forms and Flattened Documents Chapter 3 Converting Word Documents PegaRULES Process Commander makes available to your Process Commander applications a printer driver from Amyuni Technologies that converts.doc files to PDF files. You can configure this feature in either of the following ways: As a client-side process. That is, a flow action can call the printer driver on the user s workstation. Process Commander provides a sample flow action, Convert Attachment to PDF, that illustrates how to convert work object file attachments from.doc files to PDF. As a background process managed by PegaDISTRIBUTION MANAGER (PDM). In this case, a utility activity saves the Word document to a shared folder and adds a row to the PDM Requests table. PDM converts the Word document to PDF format, and an activity in the Pega-ProCom agent retrieves the converted files and attaches them to the appropriate work objects. This chapter explains how to use both options.

32 Working with PDF Forms and Documents Converting Word Documents 29 Client-Side PDF Conversion Option With this option, the printer driver is packaged in the Process Commander ActiveX control named propenauthoring, which is downloaded to the user s browser. Process Commander provides a sample flow action, Convert Attachment to PDF, that prompts the user for input about the attachment to be converted and what to name the converted file. The flow action then invokes a method in the ActiveX control to convert the file. You can use the sample flow action as it is, or you can use the sample rules to configure your own flow actions. The ActiveX Control and the Printer Driver The printer driver that converts the.doc files is made available through one of the Process Commander ActiveX controls, the propenauthoring control. The driver is named PRPC Amyuni PDF Converter. When the appropriate method of the propenauthoring ActiveX control is invoked, the ActiveX control determines whether the printer driver is installed, and if not, installs it. Then the driver converts the document to PDF, sets the document permissions to allow all, encodes the PDF to Base64, and returns the document. If the driver encountered any errors, it reports them. The method that completes the conversion is sdocumenttopdfconvert. It takes two input parameters: The source file to be converted, which must be a Base64 encoded string. Files attached to Process Commander work objects as file attachments are already encoded correctly. The file type of the file to be converted. The file type must be specified as DOC. The sample flow action Work-. ConvertAttachmentToPDF uses the Javascript in the HTML rule Work-.ActionConvertAttachmentToPDF to invoke the sdocumenttopdfconvert method. The following is a code snippet from the ConvertToPDF Javascript function in that rule: function ConvertToPDF() { if(oopenauthor==null) { document.all["conversioninprogresstd"].style.display = "none"; return; } swordsource = document.all("filesource").value; sresult = oopenauthor.sdocumenttopdfconvert(swordsource, "DOC");

33 30 Converting Word Documents Client-Side PDF Conversion Option... } Error Messages If the propenauthoring ActiveX control was unable to install the printer driver, to use the printer driver, to successfully convert the file, and so on, it returns an error message. Figure 12 describes the possible error messages: Error Cannot install Amyuni printer driver Cannot save document to disk Cannot create Word.Application object Document is locked Amyuni OCX not present Document does not exist Amyuni driver print call failed Description A problem during installation caused the installation to fail. When this happens, check the list of printers installed on your system. If the PRPC Amyuni driver is listed, delete it. Then try again. In the first step of the conversion process, the driver tries to save the source the Base64 encoded string to your local drive. This error occurs when the Word source document cannot be saved: perhaps you don t have write privileges on your workstation. Verify that you have the appropriate privileges and try again. Typically, this error means you do not have Microsoft Word installed on the workstation you are working on. You cannot use this printer driver unless Word in installed on your computer. The printer driver writes the PDF document to a temporary name and path on the local drive. In the very rare case that you already have a file with that name in that exact location and the document is open, this error is reported. Typically, this means that the propenauthoring ActiveX control is from an earlier version of Process Commander that does not support this feature. You must have PegaRULES Process Commander version 4.2 Service Pack 6 in order to use this feature. The input parameter for the source document did not contain the document. Be sure to check for this condition in your code before the code invokes the printer driver. For an example, see the sample HTML rule. This error is reported if the document conversion failed for any reason. Figure 12. Possible Error Messages from the propenauthoring ActiveX Control

34 Working with PDF Forms and Documents Converting Word Documents 31 The sample implementation does not just report the errors as they are reported from the ActiveX control. The HTML rule ActionConvertAttachmentToPDF takes error reporting one step further by using a localizable string held in a field value rule (Rule-Obj-FieldValue) as the text for the message it displays in the user s browser window. The sample includes ten message label field value rules. Sample Rules The Convert to PDF sample flow action is implemented through a flow action rule, an HTML stream rule, and several activities. You can use the flow action as it is just associate it with an assignment in your flow or, you can use the sample rules and activities to design your own. The Convert to PDF sample uses the following rules: Work-.ConvertAttachmentToPDF the flow action that presents the Convert to PDF function. Work-.ActionConvertAttachmentToPDF the HTML rule that renders the flow action form. It uses the following activities: Work-.IdentifyCategorizedAttachment Work-.AttachConvertedPDF the After this Action activity that saves the newly converted PDF file as a file attachment. ConvertAttachmentToPDF Flow Action The flow action rule Work-.ConvertAttachmentToPDF appears in the list of flow actions available in a work object harness as the Convert to PDF option. When a user selects this option, the following occurs: 1. A form with three fields is displayed: Convert from, Note, and Save to. 2. The user selects the attachment category of the document he or she wants converted from the list displayed in the Convert From field. 3. The flow action invokes the HTML rule Work-.ActionConvertAttachmentToPDF. 4. The HTML rule locates the last.doc file that was attached to the work object as the specified category, uses the propenauthoring ActiveX control to convert the file to a PDF file, and displays the name of the file and a success message in the flow action form. 5. The user then enters a note, selects the attachment category to use when attaching the new PDF document to the work object, and clicks Submit.

35 32 Converting Word Documents Client-Side PDF Conversion Option 6. The flow action calls its After this Action activity, Work-.AttachConvertedPDF, passing the activity values for its five input parameters. 7. The activity saves the PDF as a file attachment, creating a link between the work object and the attachment. When using the Convert to PDF flow action in your flows, consider the following: It must be called in the proper sequence. That is, design the flow so a user has added a file attachment before selecting the Convert Attachment to PDF flow action. For example, you could design the flow so that the Add Attachments flow action is used before the Convert to PDF flow action. The last.doc file attached as the selected category is the one that is converted. If your flow is designed such that it is possible to have more than one file attachment identified by the same attachment category, it should be clear that the user is to add an attachment and convert the attachment before adding another attachment in the same category. Remember that users must have the appropriate privileges assigned to their roles in order to add attachments to work objects. ActionConvertAttachmentToPDF HTML Rule The Work-.ActionConvertAttachmentToPDF HTML rule provides the code that creates the form for the Convert Attachment to PDF flow action. Before this HTML rule can be invoked, the following must be true: A work page must be on the clipboard. The work object represented by the work page must have at least one.doc file linked to it as a file attachment. The HTML rule has one input parameter: OriginalCategory. It must hold the value of the attachment category of the.doc file to be converted. When the Convert to PDF flow action invokes the Work-.ActionConvertAttachmentToPDF HTML rule, the HTML rule does the following: 1. Renders the flow action form Convert Attachment to PDF. This form displays three fields: Convert from, Note, and Save to. 2. Uses the Work-.ListOfCategorizedAttachments activity to obtain the list of files attached to the work object and displays their attachment categories in the Convert from field. 3. Uses activity to obtain a list of all the attachment categories appropriate for the work object and displays the list in the Save to field.

36 Working with PDF Forms and Documents Converting Word Documents When the user selects an option from the Convert from field, puts the value in the OriginalCategory parameter. 5. Passes both the OriginalCategory parameter and the identity of the work object (pzinskey) to the Work-.IdentifyCategorizedAttachment activity; the activity locates the most recent file in the attachment category specified by the OriginalCategory parameter, and returns it in the FileSource parameter. 6. Invokes the sdocumenttopdfconvert method of the propenauthoring ActiveX control. It passes in the contents of the FileSource parameter and specifies that the document type of the source is DOC. The OpenAuthoring control converts the.doc file to a PDF document, setting the document permissions to allow all. The ActiveX control then encodes the PDF to Base64 and returns it to the ActionConvertAttachmentToPDF rule. If there were errors during the conversion, the ActiveX control returns the error message instead of the PDF file. 7. Puts the PDF file in the strfilesource parameter. (The AttachConvertedPDF activity copies the value from strfilesource to the pyattachstream property on the file attachment page when it runs.) Note that if an error was returned rather than a PDF file, the HTML rule displays the error message. 8. Writes the name of the file to the strfilename parameter. 9. Returns to the Convert Attachment to PDF form where it prompts the user to enter some text in the Note field, select a category from the Save to field, and click the Submit button. 10. On submit, returns strfilename, strfilesource, Note, and Category to Process Commander. When the HTML rule finishes, the flow action ends. Next, the After this Action activity, Work-.AttachConvertedPDF, is invoked. Message Label Field Value Rules As described in Error Messages on page 30, the file attachment PDF conversion sample uses the text from 10 field value rules for the error messages displayed by the HTML rule ActionConvertAttachementToPDF. The Applies to class of the rules the field name is pymessagelabel, and the field values are as follows: AmyuniOcxRequired CannotCreateWordApp CannotInstallDriver

37 34 Converting Word Documents Client-Side PDF Conversion Option CannotSaveDoc CannotSetDefaultPrinter DocumentDoesn texist DocumentLocked NoFileSource PDFConversionError PrintCallFailed Open the HTML rule and examine the code in the set error messages section. This section maps a printer driver error message to the appropriate field value rule. When the printer driver returns an error, the HTML rule displays the text from the appropriate field value rule. AttachConvertedPDF Activity Rule The Work-.AttachConvertedPDF activity is the After this Action activity for the Convert Attachment to PDF flow action. Before an activity or flow action can call this activity, the following must be true: A work page must be on the clipboard. The work object represented by the work page must have at least one PDF file linked to it as a file attachment. The AttachConvertedPDF activity has five input parameters, as described in Figure 13. Parameter InsHandle Note pycategory strfilename strfilesource Description The work object ID: the value of the work object s pzinskey property. A value for the pynote property. Typically, a brief description of the file attachment. The name of the attachment category under which the file should be listed in the History and Attachments window for the work object. The name of the PDF file. The Base64 encoded PDF byte stream. Figure 13. Input Parameters for the AttachConvertedPDF Activity The Convert to PDF flow action has values specified for each of these parameters on the Action tab, as shown in Figure 14.

38 Working with PDF Forms and Documents Converting Word Documents 35 Figure 14. After This Action Section of the Action Tab for Convert to PDF Therefore, when this activity is invoked by the flow action, values for all five parameters are provided. When called, the Work-.AttachConvertedPDF activity does the following: 1. Creates a page for the file attachment, a page of class Data-WorkAttach- File. 2. Copies the value of the InsHandle parameter to the pxrefobjectkey property on the file attachment page. 3. Copies the value of the Note parameter to the pynote property on the file attachment page. 4. Opens the work object and updates its history. 5. Copies the value of the strfilename parameter to the pxattachname property and the value of the strfilesource parameter to the pyattachstream property on the file attachment page. 6. Saves the PDF file as an attachment, creating a link between the work object and the attachment. 7. Reports any errors.