Magnolia 5.7 reached extended end of life on May 31, 2022. Support for this branch is limited, see End-of-life policy. Please note that to cover the extra maintenance effort, this EEoL period is a paid extension in the life of the branch. Customers who opt for the extended maintenance will need a new license key to run future versions of Magnolia 5.7. If you have any questions or to subscribe to the extended maintenance, please get in touch with your local contact at Magnolia.
This module is deprecated. See Deprecations.
Magnolia SugarCRM Connector makes lead capture and personalization easy! Create lead capture forms in SugarCRM. Magnolia fetches the forms from Sugar and displays them to your website editors as a user-friendly list. Editors can embed a form on the website with a few clicks. Magnolia does the technical heavy lifting; editors don't need to edit HTML or copy-paste code snippets. When a visitor fills the lead capture form on your website a lead record is created for them in SugarCRM instantly.
You can tailor the user's journey with personalized content. SugarCRM lead details are available for content targeting in Magnolia. Offer the visitor relevant content. For example, if the lead has already visited your product page you could show them a video next, or point out the location of the nearest retail store since you know the visitor's city.
Installing
<dependency> <groupId>info.magnolia.sugarcrm</groupId> <artifactId>magnolia-module-sugarcrm</artifactId> <version>1.2</version> </dependency>
If you are adding the module to a Magnolia EE bundle, add also the following:
Configuration
- Provide a URL of your SugarCRM instance (@
/module/sugarcrm/rest-client/sugarCrmHttpClient/baseUrl
). - Provide an admin username and password (
adminUserName
andadminUserPassword
in/module/sugarcrm/config
). REST calls to SugarCRM need to be done as administrator.
(See also more information about user authentication.)
sugarcrm config clientSecret * clientId * adminUserPassword * adminUserName * rest-client sugarCrmHttpsClient class info.magnolia.resteasy.client.RestEasyClientDefinition baseUrl clientFactoryClass info.magnolia.resteasy.client.factory.RestEasyClientFactory commands dialogs templates traits Node name Value https://<YOUR_SUGAR_CRM_INSTANCE>/rest/v10/
SugarCRM Web to Lead forms implementation
The module is configured in /modules/sugarcrm/external-form-service
. Below you'll find out how to send emails and use personalization based on the information retrieved from SugarCRM.
Mailing
Via SugarCRM you can send pages as mails from Magnolia:
- Go to the Pages app.
- Choose a page to be sent, for example a newsletter. This page has to be already published to the public instance.
- Click the Preview page action.
- Click the Send as SugarCRM mail action.
- Fill in the required information:
- The Target List defined in SugarCRM.
- Status. Choose Ready if you want to send the email immediately, utherwise use Draft.
- Links base URL is the domain or subscriber URL from which the page should be requested.
- Click Send.
Personalization
Sample demo pages in the Travel demo, such as http://localhost:8080/magnoliaAuthor/travel/sugarcrm.html, contain traits which are handled by the Personalization module. When retrieving information from SugarCRM to provide personalized content, you don't need to create a custom trait: the Lead
capture trait is provided out of the box.
For more information about creating personalized content with traits in Magnolia, please see Creating custom traits.
Trait detector
The trait detector is the filter which retrieves external information, for example the SugarCRM Lead
information. You need to specify for each trait which information you want to retrieve (Campaign, Opportunity and so on):
sugarCrmModuleName
– a CRM module name, for example theLead
module.path
– the REST call path, for example{sugarCrmLeadId}/link/accounts
retrieves all the accounts related to the detected lead(s).filter
– a map containing properties to filter records, for example for the Lead it's only the id of the detected lead, so you can use the{sugarCrmLeadId}
variable, which will be replaced with the id of the detected Lead user before sending the request to the SugarCrm instance.fields
is optional. You can define a collection of properties which you want to retrieve, otherwise all the properties will be retrieved, which may result in requesting an unnecessary large amount of data.
The trait configuration is done in config traitDetectorConfigs Lead commandName SugarCrmLeadCommand filter id {sugarCrmLeadId} fields name name billing_address_country billing_address_country billing_address_city billing_address_city twitter twitter billing_address_state billing_address_state facebook facebook billing_address_street billing_address_street googleplus googleplus billing_address_postalcode billing_address_postalcode/modules/sugarcrm/config/traitDetectorConfigs
:Node name Value
Trait voter
A trait voter decides if a certain page variant has to be served to the current user or not. There's not much difference between a SugarCRM trait voter and any other voter. We suggest using the default info.magnolia.sugarcrm.personalization.SugarCrmVoter
, which expects the value stored by a UI field in a string in the format <moduleName>-<fieldName>-<valueName>
, for example Lead-preferred_language-en_US
.
Preview parameter converter
Parameter converter is needed for Personalization Preview. It converts String to a corresponding trait class holding a json and vice versa. For SugarCRM traits, the default is info.magnolia.sugarcrm.personalization.SugarCrmParameterConverter
.
Custom commands
Under sugarcrm commands sugarCRM SugarCrmLeadCommand class info.magnolia.sugarcrm.command.SugarCrmCommand module Lead SugarCrmMailCommand class info.magnolia.sugarcrm.command.SugarCrmCommand module Mail/modules/sugarcrm/commands/sugarCRM
you can configure custom commands which perform REST calls to SugarCRM. For basic calls use the info.magnolia.sugarcrm.command.SugarCrmCommand
class and set the module
property to the name of the SugarCRM module.Node name Value path
and body
parameters are optional. In the JAVA code below, see for example a PUT
REST call to <YOUR_SUGAR_CRM_INSTANCE>/rest/v10/Accounts/<CURRENT_SUGARCRM_USER_ID>
.
SugarCrmCommand parameters | |||
Description | Constant in info.magnolia.sugarcrm.command.SugarCrmCommand | Default value | Available values |
---|---|---|---|
Path | PARAMETER_PATH = "sugarCrmPath" | Empty string | A string representing the path after module name. |
Method | PARAMETER_METHOD = "sugarCrmMethod" | Not defined | info.magnolia.sugarcrm.command.SugarCrmCommand# METHOD_GET / METHOD_PUT / METHOD_POST |
Request body | PARAMETER_BODY = "sugarCrmBody" | Empty body | An instance of org.codehaus.jackson.JsonNode . |
public class MyTestClass { private final RestEasyCommandsManager commandsManager; @Inject public MyTestClass(RestEasyCommandsManager commandsManager) { this.commandsManager = commandsManager; } public JsonNode execute(final String command, final String path, final Map<String, Object> parameters) throws Exception { Map<String, Object> parameters = new HashMap<String, Object>(); parameters.put(SugarCrmCommand.PARAMETER_METHOD, SugarCrmCommand.METHOD_PUT); parameters.put(SugarCrmCommand.PARAMETER_PATH, path); return this.getCommandsManager().executeCommand(SugarCrmCommand.DEFAULT_SUGAR_CRM_CATALOG, commandName, SugarCrmCommand.PARAMETER_RESULT, parameters); }} }
A demo use case
SugarCRM user
- Creates a campaign.
- Creates or has an account.
- Creates a web to lead form connected to the campaign and the account.
- Uploads the file with the form as a SugarCRM document. The document's name has to have the pattern expected by Magnolia. The pattern is configurable under
/modules/sugarcrm/external-form-service/sugarCRM/externalFormConnector/documentNameFilter
, the default patern is$starts WebToLeadForm
, meaning that every document name starting with "WebToLeadForm" is considered as containing a web to lead form and is displayed as an available SugarCRM form in Magnolia.
Magnolia editor
- Adds the
sugarcrm:components/externalForm
component to a page (or uses the prepared demo http://localhost:8080/magnoliaAuthor/travel/sugarcrm.html). - Uploads the file with the form which he has received from the SugarCRM user.
- When the page is published, the SugarCRM form lives on the Magnolia page.
(External form dialog.)
Magnolia content strategist
For example, adds the SugarCRM language preference to the Americas Economic-regions segment:
Public user
- Visits the published site.
- If interested in the offer, the visitor fills in the form and submits it.
- A Lead is created in SugarCRM for this visitor.
- The User might revisit the form: The form is pre-filled with the current information from SugarCRM.
- The user may change the information and resubmit it:
- With each visit to the site, the user is detected, which is an information that may be used to provide personalized content. For example, if the user has selected English (US) as the preferred language, he may be considered to belong to the America region even though his current connected-from location may be different (non-US). See the demo page http://localhost:8080/magnoliaAuthor/travel/contact.html, which keeps providing the American contact information for the user until he changes the preferred language:
- Similarly, the demo's homepage offers the tours according the tour type selected in the form: