How to create activities that attach files to work objects
Because many applications prompt users to attach files such as correspondence to work objects, there are several standard flow actions that create work object attachments. For example, the standard Work-.AddAttachments flow action enables users to upload a single file and select a category for it while Work-.AddMultipleAttachments enables user to select multiple files and choose a category for each.
However, there are times when you need to configure this kind of processing yourself. For example:
- If the same file should be attached to every work object from a certain work type, there's no reason to use a flow action and require user input.
- If you are using the SmartForms feature to create PDF forms or documents or to process incoming PDF forms, you might want to attach the original PDF to a work object. For information about this feature, see Working with PDF Forms and Documents
- If you are configuring an application that enables users to convert Word .doc files to PDF files, you might need to modify one or more of the standard rules that support the standard Convert to PDF flow action. This feature is also described in Working with PDF Forms and Documents.
- How to configure an email service to use an email attachment as a work object attachment describes another case in which you need to configure the attachment processing yourself.
This article describes how work object attachments are linked to work objects and explains how to configure activities that attach files to work objects.
A file attachment for a work object is an instance of Data-WorkAttach-File. The attachment is connected to its work object through a link object, an instance of Link-Attachment.
Work object must exist
The work object must exist before you can create a work object attachment for it. That is, the work object must be committed, not just saved to the deferred operations list with an Obj-Save method, before you can attach something to it.
Two parts to attachments
Creating attachments is a two-part process: an activity must create the attachment object (of class Data-WorkAttach-File) and then it must create a link object (of class Link-Attachment) that connects the attachment to the work object.
Files must be Base64 encoded
The file must be stream encoded to Base64 before it can be saved as an attachment.
- If you are working with the SmartForms feature, you use the AttachEForm activity to save a PDF file as a work object attachment – it takes care of the encoding.
- When an email listener processes an email message, it Base64-encodes any email attachments and puts them on a page named pyAttachments of class Data-ServiceMessage.
- When a user creates an instance of Rule-File-Binary to store an image, PDF, or other binary file, Process Commander Base64-encodes the file when the file is uploaded.
If the file that you want to attach to a work object has not already been encoded, you must configure the activity to Base64-encode the file before it puts the file on the attachment page. You can use the Encode() function from the PegaRULES.Default function library.
Properties to set on the attachment page
When the activity creates the attachment object (of class Data-WorkAttach-File), it must set values for the following properties:
- pxAttachName – the name of the file
- pyAttachStream – the Base64 encoded file stream (this is the file itself)
- pxAttachedBy – operator ID of the user attaching the file. You obtain this value from the requestor page. For example, pxRequestor.pyUserIdentifier
- pxAttachKey –the date the file is saved as an attachment (a timestamp)
- pxRefObjectKey – the pzInsKey of the work object it is getting attached to (pyWorkPage.pzInsKey)
- pyNote. Although not a required field, you should always set a value for the pyNote property so an entry is written in the audit trail (history) when a work object obtains an attachment. Notes are limited to 60 characters.
Properties to set on the link object page
When the activity links the attachment to the work object, it should set a value for pyCategory on the link object page. If you do not specify a category, files will be listed under the category “Other Files.”
Summary of Pages and Classes
Following is the list of pages that the activity uses:
- pxRequestor (of class Code-Pega-Requestor). You use this page to obtain the user identifier of the operator attaching the file when setting the value of pyAttachedBy
- An attachment page of class Data-WorkAttachFile, typically named something like NewAttachment
If you are using the SmartForms feature, you also need a page of class Code-Pega-eForm.
Summary of activity steps
Activities that create the attachment objects and link them to work objects include the following general steps:
- Create a page for the work object attachment (Data-WorkAttach-File class).
- Put the file on the attachment page.
- Save the attachment page (Obj-Save method).
- Create a link object (Link-Attachment class) that connects the attachment to the work object with the Link-Objects method.
There are additional steps, depending on the kind of file and what your goals are. For example, if your goal is to attach email attachments, you need a preliminary step that extracts the attachments from the Data-ServiceMessage page. If you are attaching a file stored in the PegaRULES database, you need a preliminary step that gets the file.
Note: Normal flow processing commits a work object after it has been updated, so in most cases you should not include a step that commits the work object. If yours is a special case and you do need to commit the work object during custom processing, use the standard activity Work-.CommitWithErrorHandling. Do not use the Commit activity method. For more information about when work objects are committed, see Designing Applications that Ensure Data Integrity.
The examples illustrate two ways to configure the utility activity.
Note the following:
- Because the activity runs as the last step before the flow ends, it is clear that the work object exists by the time the activity is invoked.
Example 1: Using activity methods
The first example shows how to use the activity methods Obj-Open-By-Handle and Link-Objects to create a work object attachment. Figure 1 shows the Pages and Classes tab of the example activity.
Figure 1. Pages and Classes, example 1
Figure 2 shows the steps from the first example activity.
Figure 2. Activity Steps, example 1
Figure 3 shows step 1:
Figure 3. Step 1, example 1
The InstanceHandle parameter is set to the value of the binary file rule's pzInsKey property.
Tip: To get the value of a rule's pzInsKey, open the rule, click the Rule Data toolbar button, and then search for pzInsKey on the page that appears.
Figure 4 shows the Property-Set step (step 2):
Figure 4. Step 2, example 1
This step copies the file to the pyAttachStream property on the AttachmentPage. It also copies or sets other property values that Process Commander needs to create a work object attachment: pxAttachName, pxAttachedBy, pxAttachKey, pxRefObjectKey, and pyNote. Note the following:
- The value set in pxAttachName includes the file type. If you do not specify a file extension for the file, Process Commander cannot determine how to display the file when you click it in the Attachments window of the work object.
- The value specified for pyNote ensures that the value is within the character limit (60) for a note.
Figure 5 shows the Link-Objects step, step 4:
Figure 5. Step 4, example 1
To set additional properties on the link object page, use the LinkPageProperty and LinkPageValue parameters. For example, to identify a category for the attachment, you specify the pyCategory property as the LinkPageProperty and specify the category with the LinkPageValue parameter, as shown in Figure 5.
The Link-Objects method writes the link operation to the deferred operations list. When the activity finishes and returns control to the flow, normal flow processing commits the work object and the attachment.
Example 2: Using the standard eForm activities
Figure 6 shows what the Pages and Classes tab looks like:
Figure 6. Pages and Classes, example 2
As described in Working with PDF Forms and Documents, the Code-Pega-eForm class is a help class for working with PDF files. The eForm activities use pages of this class as temporary storage locations for the PDF files while manipulating the files.
Figure 7 shows the steps.
Figure 7. Activity Steps, example 2
Step 1 creates the eForm page; step 2 calls the GetEFormFromRuleFileBinary activity on the eForm page; step 3 passes the PDF now located on the eForm page to the Work-.AttachEForm activity, while creates the work object attachment.
Figure 8 shows the step that calls the GetEFormFromRuleFileBinary activity.
Figure 8. Step 2, example 2
This activity retrieves a PDF form or document from a binary file rule instance and puts it in the pyEForm property on the eForm page. This activity takes the three keys to the binary rule as input parameters: Application Name (typically webwb), File Name, and File Type
Figure 9 shows the step that calls the Work-.AttachEForm activity.
Figure 9. Step 3, example 2
This activity retrieves the PDF file from the pyEForm property on the eForm page (PrivacyPolicyEForm) and links it to the work object on pyWorkPage as a work object attachment. The input parameters for this activity are those shown in Figure 9. Note the following:
- The value for FileName includes the .pdf file extension.
- The pyCategory parameter is optional, but if you do not specify a category, the file is categorized under Other Files in the Attachment window for the work object.
- Because this activity is called without user interaction (it's called from a utility activity rather than a flow action), the SuppressHTML parameter is selected.
The two activities used to illustrate this article are available here:
The activities are named PegaSample-Task.AttachPrivacyPolicy and PegaSample-Task.AttachPrivacyPolicyEForm.