Introduction
The Sugar Connector for BusinessCraft provides the ability to transfer data between the Sugar CRM System (Sugar) and BusinessCraft. The Sugar Connector currently provides the following integration points:
Sugar Accounts to BusinessCraft Customers
Accounts in Sugar are used to create/update Customers in BusinessCraft when the first Opportunity for that Account reaches a user defined Sales Stage. Default mapping of fields is provided but can be user defined. BusinessCraft Customer Code information is written back to Sugar Accounts.
Sugar Contacts to BusinessCraft Customer Contacts
Contacts in Sugar are used to create/update Customer Contacts in BusinessCraft when the Account for that Contact/s is used to create a Customer in BusinessCraft. Default mapping of fields is provided but can be user defined. BusinessCraft Customer Contact and Customer Code information is written back to Sugar Contacts.
Sugar Opportunities to BusinessCraft Contracts
When a Sugar Opportunity reaches a user defined Sales Stage that Opportunity is used to create/update a Contract in BusinessCraft. This triggers the creation of Customers and Customer Contacts in BusinessCraft for the Account and Contact/s linked to the Opportunity. Default mapping of fields is provided but can be user defined. BusinessCraft Contract Code information is written back to Sugar Opportunities.
BusinessCraft Contract Events to Sugar Opportunities
Provides the ability to synchronise user specified events, when registered, to user-defined fields in Sugar Opportunities so that visibility of specific completed events is available in Sugar. Sugar Workflow can be used to trigger alerts and actions when the specified fields are updated in Sugar.
BusinessCraft Inventory to Sugar Product Catalogue
BusinessCraft Product Catalogue (Inventory) can be synchronised to the Sugar Product Catalogue to enable the create of quotes in Sugar using Area Pricing (Current Effective Price and All Areas only)
BusinessCraft Users to Sugar Employees
BusinessCraft Users can be synchronised to Sugar Employees to reduce rekeying of employee details in Sugar when users are already maintained reliably in BusinessCraft.
BusinessCraft Vendors to Sugar Accounts
BusinessCraft Vendors can be synchronised to Sugar Accounts with a defined Sugar Account Type.
Leads from External Web Sites captured in Sugar
Emails from leads from external web sites (Realestate.com.au and Domain.com.au currently supported) can be used to automatically create leads in Sugar. Sugar Workflow can be used to assign leads and required actions and alerts based on New Lead criteria.
System Requirements & Installation
The combination of the BCIntegrationBuilding Module loaded into Sugar and the SugarCRM Plugin enabled in the BusinessCraft Service delivers the functionality referred to as the Sugar Connector for BusinessCraft.
The following system requirements are necessary to enable use of the Sugar Connector for BusinessCraft:
Ensure BusinessCraft V5.03.02 or later is installed
Ensure that the BusinessCraft Service V5.3.2 or later is installed and running
Ensure that Synergy V10.3.1b or later is installed and that the xfServerPlus service is installed & running
Ensure the BCIntegrationBuildingIndV121_72.zip or later file has been uploaded and installed into your Sugar instance using the Sugar Module Loader.
Ensure the SugarCRM Plugin is correctly configured and enabled in the BusinessCraft Service.
Besides providing functionality within Sugar to enable the Sugar Connector, the BCIntegrationBuildingIndV121_72 Module also creates custom fields within Sugar that are essential components of the integration. Details of these fields are covered in the Sugar Custom Fields section of this document.
Sugar Custom Fields
The following fields are created in the Sugar instance being integrated to BusinessCraft when the BCIntegrationBuildingIndV121_72.zip files are installed. Please check to ensure the fields have been created otherwise the Sugar Connector for BusinessCraft will not function as expected.
If a BusinessCraft Team Member has been engaged to carry out the required installation and configuration work then this will have been checked.
Accounts Module
Contacts Module
Opportunities Module
BusinessCraft Service
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.
Service
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 Sugar Connector 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 for now as any configuration changes that are made will not take effect until the service is restarted. |
Remote Procedures
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.
SugarCRM Plugin
Click on the Plugins tab to see the currently installed plugins. In the screenshot below the SugarCRM Plugin has already been installed and is running as indicated by the green light:
| + 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 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). |
| 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. |
Add SugarCRM Plugin
To add the SugarCRM plugin, click the + Add Plugin button and complete the fields as follows:
Settings Maintenance
After creating and saving the New Plugin Details, right click on the Plugin line, select Config from the context menu and the Settings Maintenance screen for the plugin is displayed:
BusinessCraft Settings
| ODBC DataSource Name | The ODBC User DSN for the BusinessCraft dataset from which the Sugar Connector will read data. |
General
| Modules to Synchronise |
Click on the Collection field to display the which opens the SugarSyncModule Collection Editor where the individual integration points of the SugarCRM plugin can be configured in detail and enabled. This is explained in the SugarSyncModule Collection Editor section of this document. |
Lead Creation
The Lead Creation option is provided for customers who need emails from external web sites (Realestate.com.au and Domain.com.au currently supported) to be converted into Leads within their Sugar instance.
When an email arrives in the Source Email Folder from a supported external web site and is flagged as Unread, the Sugar Connector will create a Lead in the Sugar instance defined in the Sugar Settings panel and on successful lead creation, move the email from the Source Email Folder to the Archive Email Folder.
If an email arrives in the Source Email Folder from a sender other than a supported external web site, the email will be flagged as read but will remain in the Source Email Folder requiring user action.
The creation of the Lead in Sugar uses the currently known email formats from the supported external web site to populate the relevant Lead Module fields. If the email format for a supported external website changes, BusinessCraft will update the Sugar Connector as required.
| Create Leads | Indicates whether leads are to be created in Sugar from emails (True) or not (False) |
| Source Email Folder | The Email Folder where emails from the external web sites ready for lead creation are located. |
| Archive Email Folder | The Email Folder where emails from the external web sites will be stored after lead creation. |
| IMAP to Access Emails |
Details of the IMAP Email Account so that emails in the Source Email Folder can be accessed, processed and moved to the Archive Email Folder. A dropdown arrow displays the following fields: Host Name, Port Number, SSL, Email Username, Email Password. These credentials must be valid for Lead Creation to work and if not, the Sugar Plugin will report an error. |
Sugar Settings
| Sugar Password | The password for the Sugar user account used by the Sugar Plugin to carry out processing. |
| Sugar User | The user name for the Sugar user account used by the Sugar Plugin to carry out processing. The user account must have sufficient authority to carry out the processes. |
| Sugar Web Address | The web address for the Sugar instance to which this plugin line is integrated. The address must be suffixed with /soap.php |
SugarSync Module Collection Editor
Clicking on the Modules to Synchronize line in the Settings Maintenance screen and then clicking on the 
button that appears to the right of the word (Collection) opens the SugarSyncModule Collection Editor screen.
The currently supported integration points appear in the Members pane. Active Integration points are prefaced with the word Sync: whilst Inactive Integration Points are shown as DISABLED. With the appropriate level of knowledge, additional components can be added or existing components can be removed by clicking the Add or Remove buttons respectively at the bottom of the Members Panel.
The Sync Module Properties to the right contains the synchronisation settings for the selected integration point. For example, the Customers SugarToBC integration point is selected in the screen shot below and the properties for that synchronisation appear on the right-hand side of the screen:
General
The General Settings area contains high-level information regarding the integration point:
| Active | Indicates whether the integration point is active (True) or not (False). |
| Allow Create | Indicates whether the integration point can create records in the target dataset (True) or not (False). |
| Allow Updates | Indicates whether the integration point can update records in the target dataset (True) or not (False). |
| Alternate xfServerPlus Settings | Provides the option to use specific xfServerPlus settings for this integration point instead of the settings on the Remote Tab. Please note the drop-down arrow that opens a sub panel of fields to record the settings. |
| Comment | A user defined comment field to explain the nature of this integration point. |
| Description | A user defined description field to explain the nature of this integration point. |
| Direction | The direction of the integration – from Sugar to BusinessCraft (ToBCraft) or from BusinessCraft to Sugar (ToSugar). |
| Fields |
Click on the Collection field to display the which opens the SugarSyncField Collection Editor where the individual components of the SugarCRM plugin can be configured in detail and enabled. This is explained in the SugarSyncField Collection Editor section of this document. |
| Source Filter |
The filter (where applicable) to be applied to records in the source dataset in determining the records to be synchronised. For example, only synchronise Sugar Accounts to BusinessCraft where the Sugar Account Type is Customer.
|
| Sugar Module Linkage | This option provides the ability to retrieve data from a specified field in the Sugar Source Module for a Sugar record where the field in the primary module is a related record. This resolves the issue of the GUID for that record being obtained instead of, for example, the Account Name. |
Sugar Settings
The Sugar module being integrated with BusinessCraft.
| Module Name | The primary Sugar Module being integrated to BusinessCraft. |
BusinessCraft Settings
| Buffer Name | The BusinessCraft buffer used by this integration point. |
| ODBC Compare | Indicates if data is to be compared via ODBC to determine if a change in Sugar necessitates an update in BusinessCraft. If set to True, an ODBC Query is done to enable a comparison to be done between Sugar and BusinessCraft to determine if an update to BusinessCraft is required. If set to False, every change in Sugar whether necessitating an update to BusinessCraft or not will be performed. |
| SugarToBC Import Type | Advises the BusinessCraft XML importer of the type of data that will be imported. Valid values are CUST, VENDOR, PO, JOB, JCHEADA, RQ, CSHTRX, INVC, IVCMSTA, INVL, IVCLINA, TLESTL, PRODEST, IM, BM, PR, AP, OEDESP, PORECV, CONTRACT, AP. |
| SugarToBC XML Attributes |
Provides the ability to specify additional instructions that can be passed to BusinessCraft after the synchronisation has completed. For example, after creating a new contract in BusinessCraft, run the Forecast Dependency Calculation. Use the |
SugarToBC Sugar_Linked
Enables the definition of criteria for a related Sugar record that must be satisfied for the synchronisation to occur.
For example, when synchronising Contacts from Sugar to BusinessCraft, the Sugar Accounts module is checked to ensure the Sugar Account to which the Sugar Contact is linked has already been created in BusinessCraft by checking that the cusno_c field in Sugar is not blank before attempting to create the Contact in BusinessCraft.
| Linkage Destination Filter | The criteria in Sugar to be satisfied for the synchronisation to BusinessCraft to occur. For example, do not synchronise the Sugar Contact if the Customer Code field in the Sugar Secondary Module (Accounts) is blank. |
| Linkage Field Name from Destination | The field in the Sugar Secondary Module (in this example, Accounts) used to establish a link to the Sugar Primary Module (in this example, Contacts). The value of this field must match the value of the Linkage Field Name from Source field. |
| Linking Field Name from Source | The field in the Sugar Primary Module (in this example, Contacts) used to establish a link to the Sugar Secondary Module (in this example, Accounts). The value of this field must match the value of the Linkage Field Name from Destination field. |
| Linking via Relationship | Indicates if existing Sugar Relationship Logic is to be used to retrieve the record (True) or if the data is to be retrieved using the specified Secondary Module and Linkage Field from Destination information (False). |
| Secondary Module Name | The Sugar Module (in this example, Accounts) containing the field being used to specify the criteria that must be satisfied for the synchronisation from Sugar to BusinessCraft to proceed. |
BCToSugar_Linked
Enables the definition of methods and criteria for transferring specified BusinessCraft data to Sugar.
| Alternate SQL Statement | In some cases, it is not feasible to extract data required from BusinessCraft using an ODBC Query. In these circumstances a SQL Statement can be used and recorded in this field. |
| Destination Test | Allows a test to be performed on the Sugar Destination data record prior to carrying out the update in Sugar. If the test is not satisfied, the update is skipped for that record. For example, where new cost price date is greater than current cost price date. |
| Import Source | Indicates whether the extraction of data from BusinessCraft is carried out using ODBC or an xfServerPlus Call. Typically, most BusinessCraft Data is collected via an ODBC Query. Due to the complexities of the Data Structure sometimes this is not feasible. In those cases, the SugarCRM Plugin provides xfServerPlus Calls that can be selected from the drop down provided. |
| Import Source Parameter | Used to indicate the specific data to be sourced from BusinessCraft. For example, Event Number. |
| Source Tables (Additional) | If an Alternate SQL Statement is used, it is quite likely that additional tables besides the BusinessCraft Buffer defined in the BusinessCraft Settings section are to be accessed. Where this is the case, the additional tables need to be defined here, separated by a comma when there is more than one table involved. |
| Sync Updates |
Where multiple tables have been used to collect data from BusinessCraft, it is possible that multiple SyncStatus fields need to be updated in BusinessCraft. Those tables and fields can be specified by clicking on the Collection field to display the which opens the SugarSyncUpdate Collection Editor. |
SugarSyncField Collection Editor
Clicking on the Fields line in the SugarSyncModule Collection Editor screen and then clicking on the button that appears to the right of the word (Collection) opens the SugarSyncField Collection Editor screen.
The fields being synchronised appear in the Members pane. The Sync Properties to the right contains the synchronisation settings for the selected field.
For example, the BusinessCraft cusno field is being synchronised with Sugar cusno_c field and the synchronisation direction is from Sugar to BusinessCraft. As the member selected changes to the left, the settings for that field will appear to the right.
With the appropriate level of knowledge, additional fields can be added or existing fields can be removed by clicking the Add or Remove buttons respectively at the bottom of the Members Panel.
General
| Sugar Field Name | The Sugar field name. |
| BC Field Name | The BusinessCraft field name. |
| Alternate Value | Used to specify a value to be used instead of the Source data. For example, as part of synchronising Sugar Opportunities to BusinessCraft Contracts, the Contract Status in BusinessCraft needs to be populated with TBA. Record the value of ‘TBA’ in the Alternate Value field and do not record a value in the Sugar Field Name above. |
| Synchronise Data | Indicates if this field is to be included in the synchronisation (True) or not (False). |
| Linkage | Indicates if this field is used as part of the criteria to select records for synchronisation (True) or not (False). |
| Field Data Type | Choose the field data type from the drop-down list provided. |
| Numeric Size | The numeric size of the field. For example, 10000.03 has a numeric size of 8. This is very important for handling leading zeros. |
| Numeric Decimals | The number of decimals in the field. For example, 10000.03 has a numeric decimals value of 2. |
| Force Uppercase | At times, a field being synchronised might be in Proper Case but is needed to be in Uppercase in the target dataset (True) or not (False). |
| Formula | Provides the option to define a formula to be calculated with the result to be synchronised. |
| Description Field | Indicates whether this field is to be shown in Progress Reporting Emails (True) or not (False). |
| Sync Direction | Not currently implemented. Sync Direction is determined in the SugarSyncModule Collection Editor. |
Sugar to BC
| Destination Field Exists? | Indicates if the field exists in the destination table (True or False). |
| ODBC Link Key Len | The Length of the field in the target dataset. For example, Contact Sequence in BusinessCraft is a combination of the Customer Code (6 digits) and a 3-digit sequential number. In this example, the ODBC Link Key Len will be 3 being the length of the sequential number. |
| ODBC Link Key Pos | The Position of the field in the target dataset. For example, Contact Sequence in BusinessCraft is a combination of the Customer Code (6 digits) and a 3-digit sequential number. In this example, the ODBC Link Key Pos will be 7 being the starting position for the sequential number after allowing for the 6-digit customer code. |
BC to Sugar
| BC Key Field | Indicates if this field is a key field in BusinessCraft (True) or not (False) so that after syncing from BusinessCraft to Sugar, the SyncStatus can be updated in BusinessCraft. |
| Sugar Link Table Name | The Sugar table to be updated. |
After reviewing the default mappings and making any required changes, click OK and Save until the Plugins tab of the BusinessCraft Service Maintenance screen is displayed.
Settings Filename
Note the Settings Filename is populated with a path to an xml file containing the settings for the SugarCRM plugin. This file can be edited directly with a text editor instead of using the Plugins interface, however great case is required in making any changes. The file can also be copied and used for another SugarCRM plugin to save setup time where for example multiple companies are involved and only minimal differences are required in the SugarCRM Plugin settings.
Enabling the SugarCRM 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.
Testing the Sugar Connector
It is highly recommended that the Sugar Connector is tested to ensure that the data transfers carried out are as expected with a BusinessCraft Test dataset. This is of critical importance when both the Sugar and BusinessCraft datasets being integrated contain pre-existing data with each data set potentially containing valid data.
To do this change the Company field to a test dataset on the Plugins Tab and change the ODBC DataSource Name in the Settings Maintenance screen.
Sugar Accounts and BusinessCraft Customers
Where BusinessCraft contains valid data that should not be overwritten by the Sugar Connector, it is recommended that the Customer Data (CUSMASA) is exported from BusinessCraft and used as the basis for updating the Sugar Accounts data prior to enabling the Sugar Connector.
Sugar Contacts and BusinessCraft Customer Contacts
Where BusinessCraft contains valid data that should not be overwritten by the Sugar Connector, it is recommended that the Customer Contacts data (IVCTBLU) is exported from BusinessCraft. Where a Customer Contact in BusinessCraft needs to be linked to a pre-existing Contact in Sugar, then the value in the ivtu_seqnum field from the Customer Contact table in BusinessCraft must be loaded into the ivtu_seqnum_c field in Sugar.
Sugar Opportunities and BusinessCraft Contracts
Where existing opportunities in Sugar have already been recorded in BusinessCraft as Contracts, it is of critical importance to prevent the Sugar Connector from duplicating contracts as well as having cross reference data from BusinessCraft back populated into Sugar.
Lead Creation in Sugar from External Web Site Emails
Obtain a valid email from realestate.com.au or domain.com.au and move the mail into the Source Email Folder and check that a Lead is created from the email and that the email is moved to the Archive Email Folder.
Other Integration Points
Use similar processes as described in the previous examples to test other active integration points in the Sugar Connector prior to commencing Live Operation for any integration point.
Please note that whilst the SugarCRM Plugin can be enabled, only the integration points that have the Active Field in the SugarSyncModule Collection Editor set to True will be operational. This provides flexibility to roll out individual components of the Sugar Connector progressively as required or to make changes to individual integration points without impacting other existing integration points operation.
Cutting over to Live Operation of the Sugar Connector
Once testing has been satisfactorily completed:
Return to the Plugins tab and change the Company field to reflect the Live dataset.
Right click on the SugarCRM Plugin line, select the Configuration option and change the ODBC DataSource Name in the BusinessCraft Settings section to the correct live dataset ODBC name.
If a test Sugar dataset was being used, change the Sugar Password, Sugar User Name and the Sugar Web Address to the details for the live Sugar dataset.
Save the changes, ensure the plug in is enabled, make sure that only the integration points to be used are enabled and then restart the service for the changes to take effect.
Provided Progress Reporting is set up correctly on the Service Tab, periodic emails are sent advising the status of the BusinessCraft Service overall as well as specifically for the Sugar Connector and each enabled integration point.
Revision 2
9th February 2018