Product
Support
Everything Else
Helix® PDF-Emailer Installation Guide

 

 

Automate Emailing Printed Forms From Helix

This is the Installation Guide for Helix® PDF-Emailer — the Product Information page is found here.

Installation of Helix® PDF-Emailer consists of structure added to your collection, along with some files placed in the /Users/Shared/ folder of your startup volume, and some configuration helper clippings, placed in your Helix RADE Clippings folder. The process is mostly automated by the Helix PDF-Emailer Installer utility, but does require that you connect PDF-Emailer to the views you want to use it with.

PDF-Emailer is only useful when it is integrated with your existing collections. However, you can also install it in an empty collection if you want to walk through the process as practice, or to see exactly what will be added to your collection.

The PDF-E User Setup utility places the files required for using PDF-Emailer on the remote (for Helix Server) or local (for Helix RADE and Engine) workstation, walks through the configuration details, and stores data in the collection to enable document handling with optimal transparency.

Adding PDF-Emailer to your collection using PDF-E Installer

  1. Open your Helix collection in Helix RADE and switch to Design Mode.
  2. Run the PDF-E Installer utility: the basic structure is added to your collection, and the utility exits leaving the new structure selected in the main collection window.
  3. Depending on your macOS Gatekeeper setting, you may need to give permission for PDF-Emailer to run on your system. Navigate to the /Users/Shared/Helix/PDF-E/ directory on your computer, and open the file named PDF-E.command. If a dialog appears informing you that Gatekeeper is prohibiting it from running, dismiss the dialog and then right-click on the file and choose Open from the contextual menu. The dialog that appears when you do this provides an option to allow this program to run.
  4. For Helix Server users, you must also configure your Server’s Mac to allow Remote Apple Events. If your Server is accessible from the internet, it is our recommendation that the account that Helix Server runs in not be given administrator capabilities. (This is a good rule for all servers.)

That’s it! PDF-E Installer is now ready to be integrated with your existing structure. If you are working directly on your Server machine and you wish to test PDF-E Installer on that machine, you should jump down to the PDF-E User Setup instructions before going on to the next section.

Integrating PDF-Emailer with your existing structure

With PDF-Emailer added to your collection, you are ready to begin integrating it into your workflow. The specific steps required will vary depending on your particular use, so this guide provides a general overview of the process, and notes the critical steps.

  1. In your collection, identify the view from which the user enters data, and the view that is to be used to print a PDF directly to email. (This may be the same view, or it may be a distinct view used for printing.)
  2. Add a command rectangle to the template — make sure to turn the “Print” property off for the rectangle — and…
    • For direct print views, attach the PDF-Email.Direct sequence to that command rectangle. (This one sequence is used for all direct print views.)
    • For indirect print views, use the PDF-E Sequence (Indirect Print) clipping to create a new sequence that connects to the indirectly printed view. Attach this new sequence to the command rectangle.
  3. Create a post that stores key data in the PDF-E.Users relation. Use the Create Post to Users clipping to create a new post that connects to the ‘PDF-E.Users’ relation — click here to see an example. — or create your own using the model shown in the sample collection. Attach this post to the Post on edit property of the view the command rectangle was added to, in the previous step.
  4. For indirect print views, modify that view’s abacus query so that it is restricted to only show the record that matches the unique key posted to the ‘PDF-E.Users’ relation. Again, the model in the sample collection (in the ‘PDF-E.Form’ relation) provides guidance.
  5. Critical: once the print template/view pair is created, it must be ‘primed’ to create a PDF:
    1. Open the view from which the PDF is to be created, choose Page Setup, and make sure the ‘Paper Size’, ‘Orientation’, and ‘Scale’ attributes are correct, then click OK.
    2. Choose Print — if the simplified dialog appears, click the ‘Show Details’ button. (This is the down arrow next to the printer name in macOS 10.6 and earlier.) — and make sure the ‘Copies’, ‘Pages’, and other settings are correct.
    3. In the lower left corner of the dialog, click the ‘PDF’ button and choose Save as PDF… from the menu.
    4. In the dialog that appears, navigate to the macOS /tmp/ folder: Press Shift-Command-G to access the ‘Go to the folder’ dialog, enter ‘/tmp/’ and click OK. Click here to see what this looks like.
    5. Back in the main dialog, save the file with the name ‘Printed From Helix.pdf’ — this must be exact or you will have to modify the script!. Click here to see the correct form. Note that you can fill in the rest of the PDF fields (Title, etc.) however you wish, but keep in mind that these settings will be applied to all PDFs created from this template/view combination.
    6. Click Save to create the PDF. (If you’ve done this setup on another view, you will be asked if you wish to replace the existing file. Replace it.)
    7. Close the view and Save the collection, to avoid accidentally losing this setup, should you do something that prompts you to discard subsequent changes.
  6. Connect PDF-Emailer to your data. In the PDF-E.Users relation are five (5) fields and three (3) abaci that are used to create an email. These must be integrated with other data from your collection via posting icons and lookup tiles. The icons are:
    • Field: NameID: This is the unique key that identifies the recipient within your collection. You may not necessarily want to include this in the email, but it is needed to retrieve the recipient’s email address, as well as other data about the recipient (full name, balance due, etc.) you want to include in the email. Always post the recipient’s unique key to this field.
    • Abacus: PDF-E.EmailAddr: The email address of the recipient. This would most likely be retrieved via lookup using the NameID.
    • Abacus: PDF-E.Subject: The text output by this abacus is used for the subject line of the email. It can be a static message, or a constructed message based on lookups, etc.
    • Abacus: PDF-E.BodyText: The text output by this abacus is inserted in the body of the email, above the PDF attachment. As with the subject, it can be a static message, calculated from data unique to the recipient, ect. It can also be left undefined, resulting in no body text being attached.
    • Field: ƒSend: A flag that indicates whether the outgoing message should be left open for the user to review, or to send it out immediately. If you do not post a value to this field, the outgoing message is left open for review. (Change the abacus default to ‘true’ to send all messages without review, or apply logic from your collection to choose which way to handle each message.)
    • Field: FormID: The unique key that identifies the record from which the print request was invoked. This can be used to customize the email subject and body depending on which form is being sent. Not used very often.
    • Field: Username: The username for the user generating the email. Each user has their own record in this relation in order to keep users from ‘colliding’ with each other. This assumes that your users all have unique usernames and that those user icons are set to only allow one user to connect through that user icon at a time. (If you already have a Users relation, feel free to integrate PDF-Emailer into that relation and to delete the PDF-E.Users relation.)
    • Field: UserVolume: Out of the box, all Macs come with the startup volume named Macintosh HD. However, some Mac users prefer to rename their disks to give their computers ‘personality.’ This field is used to locate the trigger file on each individual user’s startup volume. This data is filled in automatically by the PDF-E User Setup utility, but can also be edited through the “PDF-E Edit” view.

    You can (naturally) retrieve additional data from your collection and pass it to the script via additional data rectangles, but you would also need to modify the script to process them.

That’s it. Save the collection and move on to the User Setup instruction, below.

Enabling workstations to use PDF-Emailer

Note: these instructions are written for Helix Client/Server, which is the primary user group for PDF-Emailer. Helix RADE or Engine users should substitute RADE or Engine for all references to Client and Server below.

To use PDF-Emailer, helper files must be installed on the user’s workstation. Helix Server should be properly configured in advance, to ensure a trouble-free installation.

  1. Confirm that your Helix Server is running and has been configured for PDF-Emailer.
  2. Run the PDF-E User Setup utility. (Note: if you have run the setup on this machine before, or are setting up the server machine, a dialog warns you that the setup has already been done. Click ‘Continue’ to proceed.)
  3. The PDF-E User Setup utility presents a series of dialogs, requesting information required to establish a connection to your Helix Server…
    1. Are you connecting to a Helix Server?: Click ‘Yes’ for Helix Server, ‘No’ for Helix RADE or Engine.
    2. Enter the name of the machine where Helix Server runs.: This is the network name of the computer, not the name of your Helix collection. That is, the machine name you enter into the ‘New Connection’ dialog.
    3. Enter the account name under which Helix Server runs.: This is the macOS account name that is used to launch Helix Server, not your Helix username. This is used for the Remote Apple Events connection PDF-Emailer requires.
    4. Enter the password for that account.: This is the password for that macOS account.
    5. The information entered so far is tested to make sure a connection to Helix Server is possible. If successful, a dialog appears confirming the version number of the Helix Server it found. If the connection fails, you are given a choice of re-entering the connection information (in case you typed something incorrectly) or canceling the setup. You must be able to establish a Remote Apple Event connection to the Server before proceeding.
    6. Enter the name of the Helix collection where PDF-Emailer is used.: This is the name of the collection itself.
    7. Enter the username you use with that Helix collection.: PDF-Emailer uses the Helix Username tile to connect your Helix activity to Mail, so enter the username you use when you connect to this collection.
    8. If you want to use an email signature in your message, enter the name of that signature.: Because of a bug in Mail.app’s AppleScript implementation, you can not create an email that has both an attachment and a signature. The script works around this by making the signature part of the main message. If you want to use a signature from Mail, open Mail’s Preferences -> Signatures panel and note the name, as seen here.
    9. If you have multiple email accounts defined in Mail.app, enter the exact sender string of the account you want to send from.: Again, Mail.app’s scripting implementation is a bit quirky. In this case, you have to enter the entire text as it appears in the From popup in a mail message, as seen here.
    10. Enter the path where PDF files generated by Helix are stored.: The location Helix stores the PDF files it creates. Warning! This value must match exactly the location used when configuring views to print using PDF-Emailer. Only advanced users should change this default value.
  4. Depending on your macOS Gatekeeper setting, you may need to give permission for PDF-Emailer to run on your system. Navigate to the /Users/Shared/Helix/PDF-E/ directory on your computer, and open the file named PDF-E.command. If a dialog appears informing you that Gatekeeper is prohibiting it from running, dismiss the dialog and then right-click on the file and choose Open from the contextual menu. The dialog that appears when you do this provides an option to allow this program to run.

That completes the user setup. Now any view that contains a button that links the PDF-Emailer code will generate a ready-to-send email.

Additional Setup Notes:

  1. Once the process is working smoothly, you may wish to make the ‘PDF-E.Script’ (and your indirect print views) invisible.
  2. The ‘PDF-E’ sequences are set to Optionally show dialogs, so you can troubleshoot the process by holding the Option key down when clicking a button to which one is attached. This will bring up the Page Setup and Print dialogs so you can re-prime the print record. Note that this must be done in Helix RADE, or the Clients will work from a default print record which will not create a PDF.
  3. By default, messages are held for review, and require that the user manually send them. This is controlled via a field named ‘ƒSend’ in the ‘PDF-E.Users’ relation. To automatically send messages, post ‘true’ into that field. The sample collection demonstrates how to use a flag on the entry form to give the user the ability to switch this as the situation dictates.

What was installed:

On Server (or RADE/Engine) Startup Volume

  • In the /Users/Shared/ folder, a folder named Helix containing a folder named PDF-E containing three items:
    1. PDF-E.scptd: the PDF-Emailer code itself
    2. PDF-E.command: the trigger document that Helix ‘opens’ to run the script
    3. PDF-E.config: the configuration file containing the setup parameters entered during installation
  • In the ~/Library/Application Support/Helix/RADE/Clippings/ folder, a folder named PDF-Emailer which contains two clippings:
    1. Create Post To Users: A post icon that stores print job values in the “PDF-E.Users” relation
    2. PDF-E Sequence (Indirect Print): a sample sequence icon that can be used to connect an indirect printing method to PDF-Emailer

On User’s Startup Volume

  • In the /Users/Shared/ folder, a folder named Helix containing a folder named PDF-E containing three items:
    1. PDF-E.scptd: the PDF-Emailer code itself
    2. PDF-E.command: the trigger document that Helix ‘opens’ to run the script
    3. PDF-E.config: the configuration file containing the setup parameters entered during installation

In the Collection

  • Relation: PDF-E.Script: 13 icons. Stores the document that triggers the script.
  • Relation: PDF-E.Users: 14 icons. Stores user choice. Integrate with your own ‘user global’ or leave it as is.
  • User: PDF-E: The user the script draws data from. Easiest to leave it as is.
  • Sequence: PDF-Email.Direct: Enter record, print, trigger script, clean up.

Technical Notes

  1. For more transparent operation, a preference setting must be made in Terminal.app. (Unfortunately, this preference is not scriptable, or we would have provided a script!) To fix this, launch Terminal, choose Preferences, and note which window settings are used by default, as seen in the first image at right. Then switch to the ‘Settings’ panel and select that item in the profiles list. Then click the Shell tab, and change the When the shell exits preference to ‘Close if the shell exited cleanly’, as seen in the second image at right. You can then close the Preferences window.
  2. Temporary files (the printed PDF) are stored in the /tmp/ directory. macOS takes care to clean this up, and each print job replaces the previous one, so there is no need to worry about PDF files building up on your hard drive.
  3. Permanent files (the script and trigger command) are stored in the /Users/Shared/Helix/PDF-E/ directory. If you wish to change this location, you must edit the PDF-E.command file to point to the new location. After moving the files to the new location, open the ‘PDF-E.Script’ view and use Helix’s ‘Find And Update All’ command to make sure Helix can find it. (If you prefer to re-import the document into the ‘PDF-E.Script’relation, be sure to replace the existing record: there should only be one record in this relation.)
  4. Because of a bug in Mail.app’s AppleScript implementation, you can not create an email that has both an attachment and a signature. The script works around this by reading the signature (if specified) and making it part of the main message.
  5. Because of a bug in macOS, the name/password for remote (eppc) access to a Helix Server is not stored in the keychain. The script works around this by hardcoding the user/password into the script. Since this is stored in plain text, it presents a small security issue. The script also includes the alternative form, without the password; using this form means the user will have to enter the password to retrieve data from Helix. Once entered, it seems to ‘stick’ for some indeterminate amount of time.
  6. The file PDF-E.config (stored in /Users/Shared/Helix/PDF-E/ contains the data needed for PDF-Emailer to work with your collection. The values stored in this file are:
    1. kUseServer: Y/N to indicate whether to connect to Helix Server or to run as a stand-alone workstation.
    2. kHelixServer: The name of the computer Helix Server runs on. (The same as you would enter in the ‘New Connection’ dialog of Helix Client.)
    3. kRSUser: The account under which Helix Server runs.
    4. kRAPass: The password for that account. Note that this is stored in plain text in this file, so this account should have minimal privileges on the host machine. (Non-administrative account with Remote Apple Events access.
    5. kCollection: The name of your collection. (If your collection file has a .heap extension, include that.)
    6. kUser: The username this workstation connects to the collection as.
    7. kMailSignature: The name of the Mail.app signature file to include in messages. See the setup notes for details.
    8. kSenderString: The account name and email address from which messages are sent. See the setup notes for details.
    9. kPDFPath: The path to the printed PDF file. By default this is /tmp/Printed From Helix.pdf and should not be changed unless you really know what you are doing.
    10. kPDFUser: The name of the Helix user that contains the PDF-Emailer menu items. By default this is PDF-E and should not be changed unless you really know what you are doing. (This configuration option was added in PFD-Emailer 1.0.5.)

Important Caveat

Helix 7.0 (and all prior versions) store the ‘print record’ — the details about what happens when a specific view is printed — in the template attached to the view, not the view itself. Automated playback through a sequence uses this stored print record. Therefore, for PDF-Emailer to work consistently, a dedicated template/view pair should be created for printing the PDF.

Release Notes

1.0 Dec 31, 2014: initial release

1.0.1 Jan 2, 2015: Installer fixes

1.0.2 Mar 3, 2015: Add version number to file info; add compatibility check during installation; add delays to PDF-E.Setup sequence to avoid timing errors; additional Client configuration safeguards; save email as draft.

1.0.3 Jan 19, 2016: Add compatibility for Helix RADE 6.2.4 (6053).

1.0.4 Dec 31, 2016: Add compatibility for Helix RADE 7.0 (6175).

1.0.5 Jan 25, 2018: Add ability to specify a Helix user other than PDF-E, restore clippings, switched to compiled script bundle for better performance, renamed Helix User Setup app (was Helix Client Setup).

1.0.6 Feb 21, 2018: Fix a bug when defining an alternate PDF-E Username.