How to configure an email service to use an email attachment as a work object attachment
Frequently, the purpose of an email service is to use the information from incoming email messages to create work objects.
The messages for email services are routed by email listeners. When an email listener routes a message that has files attached to it, the listener creates a page named pyAttachmentPage (of class Data-ServiceMessage) and puts the file(s) on that page, using the properties pyAttachNames and pyAttachValues.
If you want an email service to save the attached files from incoming email messages as work object attachments, configure the service activity to extract the files from the pyAttachmentPage and attach them to the work object.
Before you begin, remember the following about email services:
- Even though the key to an email service rule does not include a service package, an email service package must exist and it must be named EmailDefault.
- You must also create an email listener and an email server in addition to the email service rule and service package.
- If the flow for the work object routes work to "current operator," the service requestor must run as an authenticated user. Specify a user ID and password that identifies a valid operator ID on the Properties tab of the Email Listener form.
Remember the following about work objects and work object attachments:
- 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 with an Obj-Save method, before you can attach anything to it.
- Creating attachments requires two steps: 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.
- You should set a value for the pyNote property so an entry is written in the audit trail (history). Notes are limited to 60 characters.
Typically you use more than one activity to accomplish this task. For example, you are likely to use a top-level service activity that calls the standard activity named createWorkProcess to create and commit a new work object. Then, the top-level activity can call an activity that creates the work attachment object and links it to the work object that was created by the createWorkProcess activity.
Activities that create the attachment objects and link them to their work objects should do the following:
- Create a page for the work object attachment (Data-WorkAttach-File class).
- Copy the file from the pyAttachment page (Data-ServiceMessage class) to the work object 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.
- Commit the attachment object and the link object.
Figure 1 shows what the Pages and Classes tab of the service activity might look like.
Figure 1. Pages and Classes
In addition to the work page and requestor page, the tab defines the page where the email message’s file attachment is stored (pyAttachmentPage), and the work object attachment page where the file attachment will be copied (NewAttachment).
Figure 2 shows the steps in the service activity might look like.
Figure 2. Service Activity Steps
Step 3 calls the createWorkProcess activity, which creates (and commits) the work object; step 4 calls an activity that adds the attachments (AddAttachment); and step 5 commits the attachments.
Figure 3 shows an expanded image of step 3. This step calls the AddAttachment activity for each element in the value list property pyAttachmentPage. pyAttachNames, in case there are multiple email attachments.
Figure 3. Looping Through the Attachments
Figure 4 shows the AddAttachment activity called in step 4 of the service activity.
Figure 4. Steps from the AddAttachment Activity
The first step creates the attachment page, NewAttachment; step 2 copies the files from the pyAttachValues property of the pyAttachmentPage to the pyAttachStream property on the NewAttachment page; step 3 saves the attachment page; and step 4 uses the Link-Objects method to link the work object to the attachments.
Figure 5 shows the Property-Set step of the AddAttachment activity:
Figure 5. Copying the Attachments
This step copies the files to the pyAttachStream property on the NewAttachment page. 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 that it ensures that the value used for pyNote is within the character limit (60) for a note.
Figure 6 shows the Link-Objects step of the AddAttachment activity:
Figure 6. Linking the Work Object and the Attachments
This step creates the link object that connects the new work object attachment to the work object. The step page is specified as pyWorkPage. Therefore, the Link-Objects method creates a link object of class Link-Attachment (LinkClass parameter) that links pyWorkPage to the NewWorkObjectAttachment page (LinkToPage parameter), which has the file from the incoming email message.
Note: 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 2, the last step of the service activity uses the Commit method to commit the deferred operations list, which commits both the work object attachment and the link object. As always for a commit step, such an activity should also evaluate the results of the commit and respond appropriately if it failed -- write the message to a page and/or the log file and rollback the changes.