Introduction
The BusinessCraft Service contains an Email/SMS Plugin providing the following capabilities:
Send email automatically using BusinessCraft Printer Templates via SMTP
Send messages using the MessageNet Short Message Service (SMS)
Send and receive messages and optionally forms using Whispir
Send messages using the Macquarie Telecom Short Message Service (SMS)
Send and receive documents using DocuSign
The plugin enables automatic emailing of template documents such as Purchase Orders, Payslips, Remittance Advices and Invoices. Templates are converted to pdf and attached to emails. Word Documents generated from the Contracts Module can also be emailed.
SMS
MessageNet provides the option to send messages to recipients and is usually configured to not provide an option to reply. The MessageNet plugin allows messaging to be configured from any BusinessCraft module that has the Document Register capability. There is an option to reply to messages, however it should be noted that replies are in the form of emails and are directed to a specified email address. MessageNet is primarily designed for one way communication to recipients.
Whispir is designed for two way communications between the sender and recipients with the option of designing and using forms to collect data. The Whispir plugin component allows messages to be sent to recipients with links to fill in a specified Whispir form. The completed form is captured by a listener within the Whispir plugin and a record is entered in the BusinessCraft Document Register for the appropriate BusinessCraft module.
Macquarie Telecom provides the option to send messages to recipients and is usually configured to not provide an option to reply. The Macquarie Telecom plugin allows messaging to be configured from any BusinessCraft module that has the Document Register capability. There is an option to reply to messages, however it should be noted that replies are in the form of emails and are directed to a specified email address. Macquarie Telecom is primarily designed for one way communication to recipients.
DocuSign
DocuSign provides the ability for documents to be digitally sent, managed and signed anytime, anywhere, on any device. The DocuSign plugin component works in conjunction with the BusinessCraft Document Register to produce a Word document from BusinessCraft with areas to be completed/signed. The BusinessCraft Service sends the document to DocuSign. DocuSign manages the completion/signing of the document. The DocuSign plugin component listens for communications from DocuSign that documents are completed and saves those completed documents into the BusinessCraft Document Register.
System Requirements & Installation
The following system requirements are necessary:
A supported version of BusinessCraft correctly installed and configured.
A supported version of the BusinessCraft Service correctly installed, configured and running.
xfServerPlus correctly installed, configured and running.
Plugins enabled on the Plugins Tab of the BusinessCraft Service.
The Email/SMS Plugin correctly configured, enabled and running.
To make effective use of the automatic emailing component of the Email/SMS Plugin, the documents to be emailed must be correctly configured in the relevant module setup and master data screens in conjunction with correctly configured Printer Templates. Refer to the Setting Up and Using Printer Templates Process Guide for more information.
To make effective use of the MessageNet and/or Macquarie Telecom SMS components of the Email/SMS Plugin, a connection to the Internet is required at any time a message is to be sent.
To make effective use of the Whispir or DocuSign components of the Email/SMS Plugin:
A permanent connection to the Internet is required.
An SSL Certificate must be installed on the BusinessCraft Server to allow secure communication from Whispir/DocuSign to the BusinessCraft Server via HTTPS. After loading the certificate into the Cert Store, it will need to have binding applied to the Application Id “4c8c97cb-5e8c-4621-8ae0-194884b75adb”. For example: netsh http add sslcert ipport=20.100.200.70:443 appid='{4c8c97cb-5e8c-4621-8ae0-194884b75adb}' certhash=123abc123abc123abc123abc123abc123abc
A domain name is required pointing to the BusinessCraft Server. Modems used by the Whispir/DocuSign plugin components will need port 443 forwarded to the BusinessCraft Server.
If the BusinessCraft Service is behind a firewall, it must be configured to allow incoming POST requests.
BusinessCraft Service - Service Tab
Click on the BusinessCraft Service Maintenance icon on the desktop or if not visible, run the BusinessCraftServiceMaintenance.exe file normally found in the Program Files > BusinessCraft > BusinessCraft Service folder on the BusinessCraft server.
The Service Tab is displayed when the BusinessCraft Service opens – the fields on this screen are explained in the BusinessCraft Service Product Guide. Only fields directly relevant to the Email/SMS Plugin setup and configuration are explained in this guide:
| Check Frequency | Ensure the Check Frequency is not too frequent – 15 seconds should be suitable. |
| Version | Check the version of the BusinessCraft Service in the bottom left hand corner of the screen to ensure it meets the System Requirements outlined earlier. |
| Service Status | Check the status of the BusinessCraft Service. It does not matter whether the service is running or stopped as any configuration changes that are made will not take effect until the service is restarted. |
BusinessCraft Service - Remote Procedures Tab
Click on the Remote Procedures tab. If xfServer Plus has not previously been installed, please ensure this is carried out before proceeding further in accordance with the xfServer Plus Installation Guide.
| Server | The server name on which xfServer+ is installed (in most cases this will be the server on which BusinessCraft is installed) |
| Port | The port number designated for use by xfServer+ (usually 2340) |
| Timeout | Used to indicate how long the BusinessCraft Service will wait for a result from an xfServerPlus call. If 0, then the default Synergex Setting of 120 seconds is used. |
| BC User Name/Password | The BusinessCraft User Name and Password that will be used by the Email/SMS Plugin to create/update records in BusinessCraft. |
| Company | The default BusinessCraft dataset to be used by all plugins using the xfServer+ service. BusinessCraft datasets can be defined on a plug in by plug in basis if required. |
Once the Default Settings have been configured, click the Test button to ensure that the settings enable xfServer Plus to operate successfully. A Log Form screen displays the results of the test.
BusinessCraft Service – Plugins Tab
Click on the Plugins tab to see the currently installed plugins. In the screenshot below the Email/SMS Plugin has already been installed and is running as indicated by the green light.
To add the Email/SMS Plugin, click on the next available line and complete the fields as follows:
| Sort Name | Provides the option to sort the plugins by ascending or descending order. The Sort column is populated with the Display Name by default but can be overwritten if required. Normally leave this column blank and it will be populated automatically. |
| Enabled | A check box that indicated whether the plugin is enabled or not. |
| Sts | The operational status of the plugin – Running (Green), Starting, Stopping or Scheduled to Start (Orange), Stopped (Red), Disabled (Black). Hovering over the indicator provides additional information related to the status. |
| Display Name | A unique user defined name for the plugin if a name other than the actual name of the plugin is preferred. |
| Plugin Type | The system defined type for the plugin. Select the plugin from the dropdown list – in this case the Email/SMS Plugin. |
| Company | Not applicable to the Email/SMS Plugin – leave blank. |
| Frequency | The polling frequency for this plugin. The Every Poll setting will poll in accordance with the Check Frequency in the Service Settings on the Service Tab. If required, other frequencies can be selected per plugin including an advanced option providing for a customised polling frequency. |
| Log | Indicates whether a log is to be maintained of activities for the plugin. |
| Settings Filename | The name and location of the file containing the settings for this plugin. This field should be left blank and will automatically populate after the Email/SMS Plugin has been configured. |
Please note that the above fields are only applied when the BusinessCraft Service is starting up, so any changes to be used requires the BusinessCraft Service to be restarted.
Configuring the Email/SMS Plugin
After creating the Email/SMS Service line, right click on the line, select Config from the context menu and the Email Setup screen is displayed. The screen comprises a Settings Panel which remains visible, with three Tabs (SMTP, SMS and DocuSign) for those components.
Settings
| Outgoing Folder | When an email is created in BusinessCraft, the folder used to store that email prior to be being sent. This folder is the email queue. |
| Sent Folder | When an email has been successfully sent, the email is moved from the Outgoing Folder to the Sent Folder. |
| Failure Folder | When an email has failed sending, the email is moved from the Outgoing Folder to the Failure Folder. Once the problem with sending has been identified, emails in the failed folder can be moved to the Outgoing Folder for sending. |
| Image Folder | The folder containing an image that can be used when carrying out a test email using the Send Test button. |
| Sent Expiry | The number of days to keep sent emails in the Sent Folder before they are automatically deleted from that folder. |
SMTP Tab
| Host | The SMTP mail server. |
| Port | The port used for sending email. |
| Use Secure Connection | Indicates whether SSL or TLS is used or not. |
| Timeout | The time allowed before a timeout is assumed to have occurred. |
| From Email | Where supported by the host mail server, the Sender Email address that will be displayed on outgoing emails. |
| From Name | Where supported by the host mail server, the Sender Name that will be displayed on outgoing emails. |
| Reply To Email | The email address to which replies are to be directed. |
| User Name | The User Account to log on to the host mail server |
| Password | The Password to log on to the host mail server. |
| CC Email | When emails are sent, copies will be sent to these addresses. Multiple addresses can be recorded separated by a semi colon. |
| BCC Email | When emails are sent, blind copies will be sent to these addresses. Multiple addresses can be recorded separated by a semi colon. |
| Failed Email | Failed emails are directed to this address when the Send Failed Emails to Failed Email Address box is ticked. |
| Test Email | When the Send Test button is activated, a test email will be sent to this address. |
| Test Attachment | The attachment to be used when sending a Test Email using the Send Test button. send with the Test Email. Useful for testing message size limits imposed by the Email Provider. |
| List ID | Specify a mailing list ID for emails sent so that those emails can be easily found without relying on sender name or emails address type searches. |
| Minimum Size | Emails with attachments smaller than this threshold will not be sent. |
| Send Sent Notification to Originator | When ticked and an email is sent, an email will be sent to the originator. |
|
Enable Delivery Notification |
When ticked and an email is delivered, a confirmation email will be sent to the sender, subject to any restrictions placed on this capability by the mail server. |
| Send Failed Emails to Failed Email Address | When ticked and an email fails delivery, an email will be sent to the failed email address. |
| Validate Email Addresses? | When ticked, email addresses are validated before sending. If an invalid email address is detected, the email is moved to the Failure Folder. |
| Send Failed Emails to the Sender | When ticked and an email fails delivery, an email will be sent to the sender. |
| Send Test | When activated, a test email will be sent to the Test Email address using the test details provided. This option uses the settings displayed on screen without the need to save allowing for iterative testing. Emails are sent from the current logged in user’s Windows account. |
| Test Service | When activated, creates an Email.XML file in the Outgoing Folder to ensure the Emailing Service account can read the Outgoing Folder and send emails. This option uses the settings displayed on screen without the need to save allowing for iterative testing. Emails are sent from the Windows User account used by the BusinessCraft Service. (e.g. System) |
| Save Button | Saves settings and closes the screen. |
| Close Button | Closes the screen without saving. |
SMS Tab
Message Settings
| Provider | Select the provider from the dropdown – currently MessageNet, Whispir or Macquarie Telecom. Different Additional Details are displayed depending on the provider selected. |
| User Name | The User Name used to log on to the selected provider’s service. |
| Password | The Password used to log on to the selected provider’s service. |
| Proxy | If applicable, details of the proxy server used to connect to the messaging server for the selected provider. |
Additional MessageNet Details
| Alt Reply |
MessageNet sends Messages from a pool of Mobile Numbers. If not ticked, messages display the sender as the mobile number used by MessageNet. When recipients reply to the SMS an email is generated to the specified Reply Email/Alias. If ticked, messages display a 10-character alias specified in the Reply Email/Alias field instead of the mobile number used by MessageNet. Recipients cannot reply to SMS using this method. |
| Reply Email/Alias | The Email Address or Alias used by the Alt Reply setting. |
Additional Whispir Details
| API Key | Enter the key generated on the Whispir web site for the Whispir Account. The key enables communication between the BusinessCraft Service and Whispir. |
| Default Workspace | If the Whispir account holder uses the multiple site option provided by Whispir, a drop-down list of workspaces is displayed when the drop down is selected. Select the default workspace to be used. If multiple sites are not used, leave the default of None. |
| Activate Listener | Whispir communicates with the BusinessCraft Service by sending HTTP (PUSH) messages. The Listener needs to be active to receive these communications. |
| Testing Template | The Whispir Template to use when sending a Test Message using either the Send Test or Test Service buttons. |
| Callback Server (W) |
The web address to which Whispir should send HTTP (PUSH) messages. |
| Site ID | Used by Whispir where the account holder uses the multiple site option provided by Whispir. |
| Callback Server (L) | The web address that the BusinessCraft Service should listen on to receive Whispir Messages. Typically, this address will be the same as the Callback Server (W). |
| API Fail Check | The Minimum Hours between checking for failed API Callbacks. (0 is disabled). |
| Failure Email | If the Whispir Server is unable to communicate with the BusinessCraft Server via the Callback Server (W) address, an email notification is sent to this address. |
| Test Listener |
Allows the Whispir plugin to listen for Whispir Requests. Note: this option cannot be used if the Whispir plugin is already running as only one application can listen for a given address. |
| Register Callback | When configuring the Whispir plugin for the first time, Whispir needs to be notified of the Callback Server (W) address to which messages are to be sent. This button executes a registration on the Whispir Web Service of the address to use. Whispir will perform a test to ensure it can reach the address, so the plugin must be running or the Test Listener option active when registering the address. |
| Show Callbacks | Sends a request to Whispir to provide a list of registered callbacks. |
| Show Failed CB | Sends a request to Whispir to provide a list of failed callbacks. |
| Clear Failed CB | Sends a request to Whispir to clear the list of failed callbacks. |
| Refetch Responses/Days | Sends a request to Whispir to refetch callback history for the number of days specified in the Days field. Zero Days indicates only fetch failed callbacks. |
IMAP to Access Emails (if different from SMTP)
Whispir has the capability of capturing photos on mobile devices, however those phots photos must be emailed to a common account using IMAP. The IMAP to Access Emails fields are provided to record IMAP details that are different from the SMTP details recorded on the SMTP Tab:
| Host | The IMAP Mail Server. |
| Port | The port used for receiving email. |
| Enable SSL | Indicates whether SSL is used or not. |
| Recheck Delay | The minimum number of minutes between checks for emails. |
| User Name | The Email Account Name to log on to the host. |
| Password | The Email Account Password to log on to the host. |
| Source Folder | The Folder for the Email Account to check for emails. Blank indicates checking is disabled. |
| Archive Folder | The Folder in the Email Account to which Source folder emails are moved after being processed. |
| Server Path | The full path for the folder on the BusinessCraft Server where images extracted from the Source Folder Emails will be saved. e.g. D:\BusinessCraft\ MapDr\Docs. |
| Workstation Path | The mapped drive path for the folder on the BusinessCraft Server where images extracted from Source Folder Emails will be saved. e.g. Q:\Docs. |
| Test IMAP | Use the Test IMAP button to check that the source folder on the mail server can be accessed using the account name and password and a list of emails can be retrieved. |
Additional Macquarie Telecom Details
| From | The Message Source MSISDN that will be used to identify the sender. Only numbers or strings registered for the Macquarie Telecom account can be used. If the details in the From field cannot be validated on the account, then the default values for the account will be used instead. |
SMS Settings
| Test Mobile No: | The Mobile Number to which test messages are to be sent. |
| Restrict Sending To: | This option prevents messages from being sent outside of the Start and End times specified. Messages generated outside these times will be saved and sent as soon as permitted by the Start Time and End Time window. |
| Start Time: | The Start Time for the window for message sending. |
| End Time: | The End Time for the window for message sending. |
| Send Test | Send a test message using the information show on the screen |
| Test Service | Creates a request for the BusinessCraft Service to send a message using the details being used by the Service that is running. |
DocuSign Tab
DocuSign Settings
| User Name | The User Name used to log on to DocuSign. |
| Password | The Password used to log on to DocuSign. |
| Integrator Key | Enter the key generated on the DocuSign web site for the DocuSign Account. The key enables the transmission of documents between the BusinessCraft Service and DocuSign. |
| Use Demo Server | DocuSign allows the use of a free testing server prior to signing up for a paid DocuSign account. Documents from this account are not legally binding and are for testing purposes only. Tick the Use Demo Server box to enable testing. |
| Callback Server | The web address to which DocuSign should send documents. |
| Test Listener | Tick this option to allow the DocuSign plugin to test listening for DocuSign communications. This option cannot be used if the DocuSign Plugin is already running as only one application can listen for a given address. |
Test
| Email Address | The email address to which test documents are to be sent. |
| Email Name | The email recipient name to which test documents are to be sent. |
| PDF File | The PDF file to be used for test purposes. |
| Send Test | Click the Test Button to carry out the test. |
After reviewing the default mappings and making any required changes, click Save until the Plugins tab of the BusinessCraft Service Maintenance screen is displayed.
Enabling the Email/SMS Plugin
For any plugin to function the Enabled tick box in the top right hand corner of the screen must be checked. To enable a specific plugin, ensure the enabled tick box next to the plugin is also checked as shown. The Sts column provides a visual indicator of the status of the plugin as follows:
Green Running
Orange Starting
Black Disabled
Red Stopped
Click Apply to save and stay on the screen or click Save to save and exit. The following message will appear advising to stop and start the BusinessCraft Service for the settings that have been changed to take effect.
| + Add Plugin | Click the + add Plugin button to add a new plugin. |
| Testing Mode | The Testing Mode check box allows the BusinessCraft Development team to test plugins without updating records. |
| Attempt Plugin Restarts | Indicates whether the BusinessCraft Service will automatically attempt to restart stopped plugins. |
| Enabled | Indicate whether BusinessCraft Service plugins are enabled or not. |
| Service Status |
|
| Version | The current build version for the BusinessCraft Service. |
| ? | Opens BusinessCraft Service Plugin Help. |
| Summary | Opens the BusinessCraft Service Configuration Summary for Plugins. |
| Stop | Stops the BusinessCraft Service. |
| Start | Starts the BusinessCraft Service. |
| Emulate | The Emulate Button provides the ability to operate the plugin using the current user login credentials rather than being run as a service. In all other respects, clicking on the Emulate Button is equivalent to enabling the plug in and restarting the service. When the user logs off the emulation stops. |
| Restart | Stops and starts (restarts) the BusinessCraft Service. |
| Save | Will save any changes made to the current settings and close the BusinessCraft Service. |
| Close | Will close the BusinessCraft Service without saving any changes made since the last save was performed. |
| Apply | Will save any changes made to the current settings and leave the BusinessCraft Service open. |
Restarting the BusinessCraft Service
As indicated by the message received when saving any changes, those changes will not take effect until the BusinessCraft Service has been restarted. To restart the BusinessCraft Service, click the Restart button.
Alternatively, if the Status of the Service is Running, click on the Stop Button and wait until the Status is Stopped. Then click on the Start Button to restart the Service and wait until the Status is Running.
Revision 2
08 February 2018