Introduction
The BusinessCraft Service provides an extensible & flexible framework for automating a range of tasks including:
Automated Sending of Emails (SMTP)
Automated Sending of Text Messages (SMS)
The BusinessCraft Service also provides numerous supported plugins that can be configured and executed on a periodic or scheduled basis.
The following topics are covered in this document:
Installing the BusinessCraft Service
BusinessCraft Service Overview
Service Settings Tab
SMTP Logging Tab
Remote Procedures Tab
Plugins Tab
Service Status Panel
Uninstalling the BusinessCraft Service
Repairing the BusinessCraft Service
Installing the BusinessCraft Service
The BusinessCraft Service is a windows service provided to all BusinessCraft customers that needs to be installed on the server that will host the service.
To download the BusinessCraft Service, go to the BusinessCraft Service Sharepoint site and select the folder containing the version required:
| BusinessCraft Service Update.zip | Contains the necessary files to carry out an update by copying the required files to the required the designated BusinessCraft Service folder. This option should not be carried out other than by experienced users. |
|
BusinessCraft Service Setup.zip |
Contains the full installation files for the BusinessCraft Service. If a full installation is carried out, any existing BusinessCraft Service must be uninstalled first. |
The Release Notes will specify any perquisites.
The installation process that follows is for a full installation:
Download the BusinessCraft Service Setup.zip, saving the file to BusinessCraft\MapDr\Releases\BusinessCraftService or an equivalent location as defined by company policy.
Check if the BusinessCraft Service is already installed and if so uninstall using the steps explained in the Uninstalling BusinessCraft Service section of this article.
Check any pre-requisites for installation by reviewing the Release Notes and ensure any prerequisite installation is carried out.
Go to the location holding the downloaded BusinessCraft Service Setup.zip and unzip the file to a temporary folder.
Go to the temporary folder and run the setup.exe file. Read the BusinessCraft Service Setup Wizard screen and to proceed, click Next:
Ensure the default installation folder is correct or click Browse to select the required folder. Ensure Everyone is selected.
The Disk Cost Button opens the BusinessCraft Service Disk Space screen that displays available drives, disk size, available space, required space and difference for installation purposes.
To proceed, click Next. Buttons are provided to go Back a step or to Cancel the installation.
The Confirm Installation screen is displayed:
To proceed, click Next. Buttons are provided to go Back a step or to Cancel the installation.
The Installing BusinessCraft Service screen is displayed. The option to Cancel is provided to quit the installation.
A pop-up may display requiring the user login and password to enable the service to run on the server on which it is being installed.
The Installation Complete screen is displayed. Click Close to exit the installation:
If errors are encountered, screen shot the error and log a ticket with full details of the error encountered and relevant screen shots so that a BusinessCraft Team member can provide the required assistance to complete the installation.
The BusinessCraft Service Maintenance icon should be displayed on the Windows Desktop:
This completes the installation process.
BusinessCraft Service Overview
The BusinessCraft Service Maintenance application is used to configure the settings for the service, stop & start the service and configure and administer required plugins for the service. Separate product guides explain the configuration and administration of each available BusinessCraft Service plugin.
To open the BusinessCraft Service Maintenance application click the icon on the desktop or select the BusinessCraft Service Maintenance menu item from the Windows Programs menu.
The BusinessCraft Service Maintenance application provides the following components:
| Service Tab | The Service Tab contains general settings for the BusinessCraft Service with sections for Service Settings, Progress Reporting and Progress Messages. |
| SMTP Logging Tab | The SMTP Logging Tab contains SMTP settings including options for delivery notification, failed emails and a test option to ensure the settings are valid. |
| Remote Procedures Tab | The Remote Procedures Tab contains settings so that Remote Procedures using xfServerPlus can be carried out. A Test option is provided to ensure the settings are valid. |
| Plugins Tab |
Provides the ability to configure and maintain a range of plugins available for the BusinessCraft Service. Each plugin can be started and stopped independently of the BusinessCraft Service, however for a plugin to function the plugin must be enabled and both the plugin and the BusinessCraft Service must be running. |
| Service Status Panel |
The Service Status Panel is displayed at the bottom of the screen regardless of the tab selected. The panel displays the status of the service, options to stop and start the service, as well the ability to Save or Apply changes. |
Service Tab
The Service tab is displayed by default when the BusinessCraft Service Maintenance application is opened:
Service Settings
| Check Frequency | Specifies the number of seconds to wait between each processing cycle. Defaults to 15 seconds. |
| User Name | Specify a user name if a user account other than the Windows Services Account is to be used by the BusinessCraft Service. The Verify User button tests the User Name and Password supplied. |
| Password | Specify the password for the User Name supplied. The Test Cred button tests the User Name and Password supplied. |
| Verify User | A Verify User button is provided to test the User Name and Password. |
| Service Folder | Specifies the folder containing the folders used by the BusinessCraft Service. Buttons are provided to select the folder and to open the logging folder. |
| ODBC User Name and Password | To be advised |
| Troubleshoot Maint | To be advised |
| Log Enabled | When checked, enables the writing of log files. |
| Debug Enabled | When checked, enables the writing of information to a debug file for development & testing purposes. |
| Mode | To be advised. |
| Warning/Error Messages to Event Log | To be advised. |
| Log Expiry | Specifies the number of days to keep log files before they are purged by the service. Value of Zero indicates no purging required. |
| Purge Expired | Initiates the Purge Expired Log Files option. The Purge Expired Option goes through the logging folder and purges any log files that are older than the number of days specified to keep. |
Progress Reporting
| Progress Email | The email addresses (separated by a semi colon) to which the status of the BusinessCraft Service and implemented plugins is sent either as Progress Report emails or Error Report emails. |
| Error Email | The email addresses (separated by a semi colon) to which Progress Email Warnings and Errors are sent. |
| Report Frequency | The frequency of sending progress reports to the Progress Email addresses. |
| Error Frequency | The elapsed time before an error report is sent to the Progress Email addresses. |
| Verbose Messaging | Indicates if Progress and Error reports contain additional detail (ticked) or not. |
| Progress Message | A simple status update of Progress and Error report emails sent including a log of BusinessCraft Service stoppages, Service Version and Service Path. |
Example of a Progress Report Email with verbose not ticked
Example of a Progress Report Email with verbose ticked
SMTP Logging Tab
The SMTP Logging Tab is used to define the email settings used to provide progress and error reporting emails. The fields displayed on this tab will vary depending on the provider selected. This document displays the Exchange (Modern Auth) view as this will be used by the majority of our customers. An overview of Exchange (Modern Auth) is provided at the end of this document).
| Provider | Choose Exchange (Modern Auth), Google, Other. Prior to the introduction of Exchange (Modern Auth), most sites would have been set to Other. |
| Tenant Id | If not known, can be found by going to the Microsoft Azure web site and using the Azure Active Directory option to search. |
| Azure Portal – App Registrations | A link provided to register the BusinessCraft Service as an app for your company with Microsoft. |
| Client Id | The Client Id provided by Microsoft when registering the BusinessCraft Service as an app for your company. |
| Client Secret | The Client Secret provided by Microsoft when registering the BusinessCraft Service as an app for your company. |
| From Email | Where supported by the provider, the Sender Email address that will be displayed on outgoing emails. |
| From Name | Where supported by the provider, the Sender Name that will be displayed on outgoing emails. |
| Reply To Email | The email address to which replies are to be directed. |
| 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 button is clicked, a test email will be sent to this address. |
| List ID | Specify a mailing list ID for progress and error emails so that those emails can be easily found without relying on sender name or emails address type searches. |
| Image Folder | The folder containing an image that will be sent with test emails. |
|
Enable Delivery Notification |
When ticked and an email is delivered, a confirmation email will be sent to the sender. |
| Send Failed Emails to Failed Email Address | When ticked and an email fails delivery, an email will be sent to the failed email address. |
| Send Failed Emails to the Sender | When ticked and an email fails delivery, an email will be sent to the sender. |
| Send | When clicked, a test email will be sent to the Test Email address. |
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 | The BusinessCraft User Name that will be used by the Sugar Connector to create/update records in BusinessCraft. |
| BC Password | The BusinessCraft Password for the User Login that will be used by the Sugar Connector 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. |
| xfSvr+ Environment Variables | A list of xfSvr+ variables to assist when the Test Button results in a failure. |
Once the Default Settings have been configured, click the Test button to ensure that the settings enable xfServer Plus to operate successfully.
The Log Form screen displays the results of the test:
Options are provided to copy the Log Form details to the Clipboard or to Save the Log Form details to a text file.
Plugins Tab
Click on the Plugins tab to display currently installed plugins, add new plugins or update configurations for existing plugins.
| + 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. |
| 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 indicates 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. |
| ? | Opens BusinessCraft Service Plugin Help. |
| Summary | Opens the BusinessCraft Service Configuration Summary for Plugins. |
Service Status Panel
| Service Status |
|
| Version | The current build version for the BusinessCraft Service. |
| 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. |
Uninstalling the BusinessCraft Service
To uninstall the BusinessCraft Service, go to the location holding the downloaded BusinessCraft Service Setup files and run the setup.exe file. Read the BusinessCraft Service Setup Wizard screen, select Remove BusinessCraft Service and click Finish:
The Removing BusinessCraft Service screen is displayed. On completion, the Installation Complete screen is displayed. Click Close to exit.
If errors are encountered, screen shot the error and create a Service Request so that a BusinessCraft team member can provide the required assistance to complete the removal of the businessCraft Service.
Repairing the BusinessCraft Service
To repair the BusinessCraft Service, go to the location holding the downloaded BusinessCraft Service Setup files and run the setup.exe file. Read the BusinessCraft Service Setup Wizard screen, select Repair BusinessCraft Service and click Finish:
The Repairing BusinessCraft Service screen is displayed. On completion, the Installation Complete screen is displayed. Click Close to exit.
If errors are encountered, screen shot the error and create a Service Request so that a BusinessCraft team member can provide the required assistance to complete the removal of the businessCraft Service.
Exchange (Modern Authentication)
Effective 1 October 2022, Microsoft will be phasing out Basic Authentication on a tenant-by-tenant basis. Full details are contained in this announcement.
This means that from a BusinessCraft Service perspective, the BusinessCraft Service needs to be registered as an app for your company and SMTP settings in the BusinessCraft Service need to be updated to reflect this. If you use an Incoming Email Plugin/s in the BusinessCraft Service, that plugin/s will also need to be updated to reflect.
Here is a summary of the steps involved:
Register the BusinessCraft Service as an app
Follow the link provided on the SMTP logging tab to go to the Microsoft Azure App Registrations page making sure you are logged in for your organisation. If the BusinessCraft Service is already registered, it will be displayed and there is no need to proceed with the registration step, other than to make sure you have the Tenant Id, Client Id and Client Secret.
If the BusinessCraft Service is not registered for your organisation, click the New Registration link and proceed to register the BusinessCraft Service. The following screenshot is provided as an example:
Click Register and a screen similar to the following will be displayed:
Select Certificates and Secrets from the side panel and then click New Client Secret:
Complete the Add a Client Secret pop up window, noting that an expiry period is needed and will need to be updated again in the future periodically:
The Certificates and Secrets page will refresh and the Value (Client Secret in the BC Service) and Application/Client Id (Client Id in the BC Service) will be displayed. Options to copy to the clipboard are provided.
Go to the API Permissions page (made need Global Administrator rights) and make sure the Mail.Read, Mail,ReadWrite and Mail.Send components within Microsoft Graph have permissions granted for your site:
Update the SMTP Logging Tab
Use the Tenant Id, Client Id and Client Secret to complete the SMTP Logging Tab as described earlier in this document.
Update Incoming Email Plugins
If your organisation uses an Incoming Email plugin, you will need to go to that plugin and update its configuration. Here is an example:
Revision 4
27th September 2022