SugarCRM connector

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>
</dependency>

If you are adding the module to a Magnolia EE bundle, add also the following:

• magnolia-external-traits.jar
• magnolia-external-forms.jar

Configuration

• Provide a URL of your SugarCRM instance (@ /module/sugarcrm/rest-client/sugarCrmHttpClient/baseUrl ).
• Provide an admin username and password ( adminUserName and adminUserPassword in /module/sugarcrm/config ).  REST calls to SugarCRM need to be done as administrator.
  (See also more information about user authentication.)

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:

1. Go to the Pages app.
2. Choose a page to be sent, for example a newsletter. This page has to be already published to the public instance.
3. Click the Preview page action. 
4. Click the Send as SugarCRM mail action.
5. Fill in the required information:
   1. The Target List defined in SugarCRM.
   2. Status. Choose Ready if you want to send the email immediately, utherwise use Draft.
   3. Links base URL is the domain or subscriber URL from which the page should be requested.
6. 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 the Lead 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 /modules/sugarcrm/config/traitDetectorConfigs :

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 /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.

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

1. Creates a campaign.
2. Creates or has an account.
3. Creates a web to lead form connected to the campaign and the account. 
4. 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

1. Adds the sugarcrm:components/externalForm component to a page (or uses the prepared demo http://localhost:8080/magnoliaAuthor/travel/sugarcrm.html). 
2. Uploads the file with the form which he has received from the SugarCRM user.
3. 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

1. Visits the published site.
2. If interested in the offer, the visitor fills in the form and submits it.
3. A Lead is created in SugarCRM for this visitor.
4. The User might revisit the form: The form is pre-filled with the current information from SugarCRM. 
5. The user may change the information and resubmit it:
   
6. 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:
   
7. Similarly, the demo's homepage offers the tours according the tour type selected in the form: 

Further reading

• Introduction to Contacts, Leads, and Targets @ sugarcrm.com
• Sugar Developer Guide 7.9