This registry entry identifies the address of your firm's e-mail server, and may be used to specify test settings such as cc’ing and redirects. It is required for implementation of Escalation Manager and Report Anywhere.
Testing Your Registry Entries
The system does not verify the validity of registry entries. Be sure to test your registry entries after completing them to verify that they are functioning correctly.
Setting Values are Uppercase-Lowercase Sensitive:
The Setting Value is case-sensitive: be sure that you enter the value exactly as specified in the documentation. If the documentation specifies a value of true, do NOT enter True or TRUE
SAMPro’s SMTP mechanism includes an Authentication mechanism for mail servers providing LOGIN authentication.
Enhanced MS Outlook support is also offered, and may be implemented with this registry entry. If this is implemented, all your SAMPro users must be running MS Outlook.
Note: Managing Emailed PDF’s
When e-mailing .PDF reports generated from SAM Pro, a copy of the report will be retained in the xmlToPdf_Sent folder located in the directory containing your SAM Pro executable (v.exe). You may wish to periodically clear or archive these files.
Id:
The Id of the Registry Entry must conform to one of the following formats:
sys-email-branchid-userid (or sys-email--userid if branches are not implemented)
sys-email-branchid
sys-email-securityid
sys-email
The first format enables you to specify e-mail parameters by branch id and/or user. A branch must be specified if a user belongs to a branch. If branches are not implement, two dashes (not separated by a space) must precede the user id.
The second format enables you to the e-mail server by security id.
The third format would apply to all users unless another registry entry was created for their security or branch/user id.
Setting Key: serversmtp Setting Value: address
where address is replaced by the address of your e-mail (smtp) server. Typically, this will be an internal IP address.
Setting Key: usernamesmtp Setting Value: name
Setting Key: passwordsmtp Setting Value: password
SAM Pro’s SMTP mechanism includes an Authentication mechanism for mail servers providing LOGIN authentication (Microsoft Exchange Server and MDaemon, for example).
Authentication and Sending PDF’s as E-mail:
If these SMTP options are specified, they must be configured properly for SAMPro to email PDF’s.
This release (used in conjunction with the xmlToPdf.jar file dated 11/8/2011) supports alternate email ports for emails with .pdf attachments (controlled by the xmlToPdf.jar file) as well as emails without pdf attachments (managed by SAM Pro). The following two additional options in sys-email are required to support this functionality:
Setting Key: portsmtp Setting Value:port# (controls emails without pdf’s)
Setting Key: smtpPort Setting Value:port# (controls emails with pdf’s)
Note that if the above options are omitted, port 25 will be the default.
SAMPro supports secure (SSL) email servers. To implement, the following additional registries are required:
Setting Key: useSSL Setting Value: true
Setting Key: MailerMethod Setting Value: Java (required to send non-pdf emails securely)
Example: Use Port 465, Secure Server
Setting Key: portsmtp Setting Value: 465
Setting Key: smtpPort Setting Value:465
Setting Key: useSSL Setting Value: true
Setting Key: MailerMethod Setting Value: Java
Note: the applicable PasswordSMTP, UserNameSMTP, and serversmtp options must also be set.
The built-in SAMPro emailer does not support Email Security. In order to utilize, you must use the Java Emailer (XMLtoPDF), enabled via MailerMethod=Java
There are 2 types of security, SSL and TLS. SSL is older/obsolete and has been replaced by TLS. It is best to use TLS when available.
By default, XMLtoPDF will attempt to use TLS initially, and will fall back to Plain (not secure) if not supported by the SMTP server and/or TCP/IP port.
If it is needed to utilize the older/obsolete SSL security method, the option UseSSL=true can be used.
Although TCP/IP ports for SMTP servers are not directly related to SSL/TLS, these typical SMTP port configurations will help for set up. Keep in mind your SMTP email provider may offer other configurations:
25 – Commonly Plain (unsecure), but can sometimes support SSL & TLS
465 – Commonly, but not limited to SSL
587 – Commonly, but not limited to TLS
Today’s standard is to use port 587 with TLS.
Example sys-email registries to use this:
Setting Key: MailerMethod Setting Value: Java
Setting Key: PortSMTP Setting Value: 587
Setting Key: SMTPport Setting Value: 587
If a From address cannot be determined, an Email cannot be sent. Especially in the case of emailing as a PDF, the XML will contain a blank emailFrom tag and the email will fail silently in the xmlToPdf_Failed folder. This release provides several enhancements to prevent Emails from attempting to send without a from address.
Setting Key: DefaultEmailSender Setting Value: validemailaddress
If a 'From' email address cannot be determined from the User's Contact Record (for reports) or the Notification Category (for Scheduled Events), this email address will be used instead.
Reports:
1. When clicking the email button on a report (if UseOutlook=false), the Sender field is now required on the SAMPro Email screen. If the Email address is not completed in the User's Contact record, the Sender field will default from the sys-mail registry's DefaultEmailSender option.
2. The Email From field in the Schedule Report screen is now required. If the Email address is not completed in the User's Contact record, the Email From field will default from the sys-mail registry's DefaultEmailSender option.
Scheduled Events: If the email-from is not set by the Scheduled Event Manager, the default email sender from the sys-email registry will be used.
Setting Key: UseOutlook Setting Value: true
If this entry is present, processing of the outgoing e-mail is passed on to Outlook with the to-address, subject, message and attachments defaulted when applicable. Older versions of Outlook may not be supported.
In Versions 9.0-9.1, UserOutlook is supported with Outlook 365/Outlook 2016. Other Outlook versions may or may not work. The appropriate XmlToPdf.jar file must also be in use. As of January 2019, the following versions (renamed as XmlToPdf.jar) are recommended:
XmlToPdf[2019-01-16] Java8-11].jar file which supports Java 8-11 but not Java 7
XmlToPdf[2017-12-27].jar to XmlToPdf.jar (Installations with Java 7 and Java 8 users)
NOTE: this is intended to be used with supports versions of Outlook. Outlook Express doesn't support the command-line attachments. Other email clients may or may not work.
If UseOutlook is enabled, the CopyAll and AutoPopulateCCAddress should NOT be enabled.
Start AP Payment Approved: and Quotemaster Vendor Approval
If Outlook is enabled, the regular SAM Pro email form will appear when the Dispute / Vendor approval button is clicked.
When Outlook is implemented, the following will occur when you click the E-mail button on a SAMPro report:
The Outlook e-mail form (not SAMPro’s) will open.
The report that you generated will be attached in its default PDF format (or as set in the registry).
The From: line will be completed with the e-mail address from your Outlook profile.
The To: line will be completed with the default values if this is supported for the report.
The Subject line will be defaulted according to the report.
The report will be attached.
When the Outlook form is up, you may add additional recipients from your Outlook address box, enter a text message, and include additional attachments. When you click Send, a copy of the e-mail will remain in your Sent box if you have implemented this feature in Outlook, as well as in the xmlToPdf_Sent folder in directory containing your SAM Pro executable.
Important Note on dbreportfiles Registry Entry and Subfolders
If UseOutlook is enabled, the directory specified by the dbreportfiles registry entry is expected to contain subfolders xmlToPdf_Sent, xmlToPdf_Failed and xmlToPdf_Retry. If they don't exist in this directory, they must currently be created manually. See Registry Entry for Report Anywhere File Path for details.
Setting Key: MailerMethod Setting Value: Java
This registry option results in Java code sending all e-mail that initiates from within the system, not SAMPro. Note that Java is used when sending e-mail with PDF attachments. This option may be utilized if difficulties with e-mail are being experienced. Do not implement this registry entry until you have discussed it with your support representative.
Setting Key: EmailReportAsType Setting Value: pdf or text (pick one option)
This entry applies to pushing the Email button on the side toolbar when displaying a report on screen. It sets the default attachment type of the report. The attachment type defaults to pdf if this option is not specified. The options of html and csv are deprecated for this global setting.
This option enables you to prevent copies of your database (which may be running for training or testing purposes) from interfering with "live" operations. Implementing this option would help avoid inadvertently emailing and pages or overwriting your real invoices while running a copy of your data to train new personnel.
You may specify either or both:
Setting Key: eng Setting Value: enginename
where enginename is replaced by the engine name that your live data runs under.
Setting Key: dbn Setting Value: databasename
where databasename is replaced by the name of your live database. Do not include the .db extension in the databasename (mydata rather than mydata.db).
Setting Key: CopyAll Setting Value: emailaddress
This option enables you to send an extra copy of all e-mail generated out of SAM Pro to a specific address or addresses (separated by commas) where emailaddress is replaced by the address you wish to copy all emails to. This option would typically be implemented for testing purposes for a limited time frame.
Tip - Service Invoice Billing
Creating a user-specific sys-email registry allows billers to send themselves a copy of their auto-mailed Service Invoices. This registry would use the format sys-email-branchid-userid (or sys-email--userid if branches are not implemented).
Setting Key: AutoPopulateCCAddress Setting Value: true
If this registry option is implemented, the system will use the currently logged in user's email address (from the contact reference in the user record) to Auto-populate the CC email address when launching the SAMPro Email formatting form. This would apply anywhere that the USER initiates the open the MANUAL email form...i.e. dispatch board, previewed report, etc.
Note: Some Manual Email Forms (like on previewed reports) do not have a CC line. In these cases, the CC address will be added to the Send to address when the email is sent.
Setting Key: RedirectAll Setting Value: emailaddress
This option enables you to redirect all e-mail generated out of SAM Pro to a specific address or addresses (separated by commas). This option would typically be implemented to avoid sending out spurious e-mails when you are running a test system.
Note - Problem Analysis if E-mails are Not Sending:
Click for troubleshooting details.
A registry entry may be used to turn on the logging of SMTP ‘conversions’ to a log file. To turn on logging for support purposes, add the following entry:
Setting Key: smtplogpath Setting Value: C:\someDirectory\someFileName.log
Setting Key: pop3server Setting Value: address
where address is replaced by the address of your pop3 server (to retrieve e-mail). Typically, this will be an internal IP address.
Setting Key: pop3user Setting Value: pop3username
where pop3username is replaced by the user's pop3 user id (for retrieving e-mail).
Setting Key: pop3pw Setting Value: pop3password
where pop3password is replaced by the user's password on the pop3 server (for retrieving e-mail).
Setting Key: pop3timeout Setting Value: timems
where timems is replaced by the time (in milliseconds) between when a request is sent and an error message is returned if timeout or other problem occurs.
Setting Key: pop3secondswait Setting Value: checkagain
where checkagain is replaced by the time (in seconds) that elapses before the inbox is checked again.
If you will be running Alarm Server on your system (to receive alarms into the SAM Pro system), you must include the following sys-email registry entry. Note that you must have a mailbox named dispatcher with the password dispatcher set up on your pop3 server to receive alarms: this is the mailbox that SAM Pro will check. Note that the terms registry entry must also be completed.
Id: sys-email
Setting Key: pop3server Setting Value: address
Setting Key: pop3user Setting Value: dispatcher
Setting Key: pop3pw Setting Value: dispatcher
Setting Key: pop3secondswait Setting Value: 60
Setting Key: pop3timeout Setting Value: 5000