SugarCRM connector

The SugarCRM module is connector for Customer Relationships Management System SugarCRM.

Download

The SugarCRM connector module is not bundled with Magnolia. You can download it from our Nexus repository as magnolia-module-sugarcrm-1.0.1.jar, or include it in your custom webapp by adding following Maven dependency to your pom.

<dependency>
  <groupId>info.magnolia.sugarcrm</groupId>
  <artifactId>magnolia-module-sugarcrm</artifactId>
  <version>1.0.1</version>
</dependency>

Make sure you're using the version 1.0.1 or higher. The passwords for Accounts created in version 1.0 are not compatible with newer versions.

Installing

SugarCRM is a Enterprise Edition module.

Click for installation steps...

Create a backup of your system before you install a module. Uninstalling a module is not as simple as removing the .jar file. Modules add and change configurations and may change the content. Try new modules in a test environment first. A module consists of a JAR file and may include dependent JAR files. Modules are responsible for updating their own content and configurations across versions. Be sure to keep only one version of each module and its dependencies.

To install a module:

Stop the application server.
Copy the module JAR files into the WEB-INF/lib directory. The location of this directory depends on the application server.
- Tomcat: /webapps/magnoliaAuthor/WEB-INF/lib
- JBoss: /server/default/deploy/magnoliaAuthor/WEB-INF/lib
Restart the server.
Go to the AdminCentral URL.
Start the Web update process.
Click Start up Magnolia.

Repeat the steps for each author and public instance.

Uninstalling

Click for uninstallation steps...

To uninstall a module, remove the module JAR file from the /WEB-INF/lib folder and restart Magnolia.

However, this is rarely enough. Modules add and modify configuration during installation. The use of a module also changes content. Removing all of these changes is difficult without knowing the installation tasks in detail.

To test a module, use the embedded Derby database and take a backup of your repositories folder. Install the module and try it. When you are done testing, remove the module JAR and restore the repositories folder from the backup. This way you can go back to square one.

We also recommend that you segregate the development and production environments. Take regular backups for disaster recovery so you can revert to a prior state in a routine fashion.

Configuration

Provide URL of your SugarCRM instance (config:/module/sugarcrm/rest-client/sugarCrmHttpClient/baseUrl).
Rest calls to SugarCRM need to be done as administrator. Please provide admin username and password (config:/module/sugarcrm/rest-client/config). More informations about user authentication.

sugarcrm
config
clientSecret	*
clientId	*
adminUserPassword	*
adminUserName	*
rest-client
sugarCrmHttpsClient
class	info.magnolia.resteasy.client.RestEasyClientDefinition
baseUrl	https://YOUR_SUGAR_CRM_INSTANCE//rest/v10/
clientFactoryClass	info.magnolia.resteasy.client.factory.RestEasyClientFactory
commands
dialogs
templates
traits

We need to authenticate Accounts to be able provide personalised content for them. Accounts are not logged into SugarCRM as Users but only into Magnolia context. You need to provide a custom text field to Accounts module via SugarCRM studio where the passwords will be stored. Define the name of this field under config:server/filters

filters
...
SugarCrmAccountAuthenticationFilter
class	info.magnolia.sugarcrm.filter.SugarCrmAccountAuthenticationFilter
passwordFieldName	password_c
SugarCrmAccountDetectorFilter
SugarCrmOpportunityDetectorFilter

Sample pages

Account page: http://localhost:8080/demo-features/modules/sugar-crm/SugarCRM-Account.html
Login page: http://localhost:8080/demo-features/modules/sugar-crm.html

Commands

The first think which we need is a command which performs rest calls to SugarCRM. You can use info.magnolia.sugarcrm.command.SugarCrmCommand class for the basic calls and set property module to the name of SugarCRM module. You need to pass method as a context attribute when executing such command. Other parameter such path and body are optional. You can see PUT rest call to YOUR_SUGAR_CRM_INSTANCE/rest/v10/Accounts/CURRENT_SUGARCRM_USER_ID in the java code below:

sugarcrm
commands
sugarCRM
SugarCrmAccountCommand
class	info.magnolia.sugarcrm.command.SugarCrmCommand
module	Accounts

Description	Constant in info.magnolia.sugarcrm.command.SugarCrmCommand	Default value	Available values
SugarCrmCommand parameters
Path	PARAMETER_PATH = "sugarCrmPath"	Empty string	A string representing 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 MyClass {
    private final CommandsManager commandsManager;
 
    @Inject
    public MyClass(CommandsManager commandsManager) {
        this.commandsManager = commandsManager;
    }
    public JsonNode execute(final String command, final Map<String, Object> parameters) throws Exception {
        Map<String, Object> ctxParams = new HashMap<String, Object>();
        ctxParams.put(SugarCrmCommand.PARAMETER_METHOD, SugarCrmCommand.METHOD_PUT);
        ctxParams.put(SugarCrmCommand.PARAMETER_PATH, MgnlContext.getAttribute(SugarCrmCommand.PARAMETER_USER_NAME, Context.SESSION_SCOPE));
        ctxParams.put(SugarCrmCommand.PARAMETER_BODY, parameters);
        commandsManager.executeCommand(SugarCrmCommand.DEFAULT_SUGAR_CRM_CATALOG, command, new SimpleContext(ctxParams));
		return ctxParams.get(SugarCrmCommand.PARAMETER_RESULT);
    }}

Personalization

The samples contain traits for Personalisation module. Those are able to retrieve informations from SugarCRM to provide a personalised content. In this chapter is described on the provided samples how you can create a custom trait . If you've never created a personalised content in Magnolia, please follow Creating+custom+traits.

Traits

A SugarCRM trait is a wrapper for json response. Extend info.magnolia.sugarcrm.personalization.trait.AbstractSugarCrmTrait for every trait you want to create since traits are identified by their java classes.

public class SugarCrmAccount extends AbstractSugarCrmTrait {   
    public SugarCrmAccount(JsonNode result) {
        super(result);
    }
}

Trait detector

Extend info.magnolia.sugarcrm.personalization.detector.AbstractSugarCrmDetectorFilter to retrieve a trait. Set command in the constructor or via config tree. Don't forgot to order your custom trait detector filter after SugarCrmLoginLogoutFilter on installation. The provided sample for detection of the SugarCRM user account sends POST request to YOUR_SUGAR_CRM_INSTANCE/rest/v10/Accounts/filter with following body:

{
   "filter":[
      {
         "id":"YOUR_SUGARCRM_USER_ID"
      }
   ]
}

public class SugarCrmAccountDetectorFilter extends AbstractSugarCrmDetectorFilter<SugarCrmAccount> {
    @Inject
    public SugarCrmAccountDetectorFilter(Provider<TraitCollector> traitCollectorProvider, CommandsManager commandsManager) {
        super(traitCollectorProvider, commandsManager);
        this.setCommand("SugarCrmAccountCommand");
    }
    @Override
    protected  SugarCrmAccount createTrait(JsonNode records) {
        return new SugarCrmAccount(records.path(0));
    }
    @Override
    protected Map<String, Object> getFilter() {
        Map<String, Object> filter = new HashMap<String, Object>();
        filter.put("id", MgnlContext.getAttribute(SugarCrmCommand.PARAMETER_USER_NAME, Context.SESSION_SCOPE));
        return filter;
    }
    @Override
    protected Class<SugarCrmAccount> getTraitClass() {
        return SugarCrmAccount.class;
    }
}

Trait voter

A trait voter decides if a certain page variant has to be served to the current user or not. There no much difference between a SugarCRM trait voter and any other voter. You can see voter which checks if the detected user has a facebook account registered in his SugarCRM account in the following code:

public class SugarCrmSocialSitesVoter extends AbstractBoolVoter<TraitCollector> {
    private boolean facebook = false;

    @Override
    protected boolean boolVote(final TraitCollector traitCollector) {
        if (traitCollector != null) {
            final SugarCrmAccount records = traitCollector.getTrait(SugarCrmAccount.class);
            if (records == null) {
                return false;
            }
            JsonNode account = records.getNode();
            if (facebook &amp;&amp; !this.isSocialSiteRegistered(account, SugarCrmAccount.FIELD_FACEBOOK)) {
                return false;
            }
            ... other social sites ...
            return true;
        }
        return false;
    }
    private boolean isSocialSiteRegistered(JsonNode account, String socialSite) {
        return StringUtils.isNotBlank(account.path(socialSite).getTextValue());
    }
    public boolean isFacebook() {
        return facebook;
    }
    public void setFacebook(boolean facebook) {
        this.facebook = facebook;
    }
}

Preview parameter converter

Parameter converter is needed for Personalization#Personalization-Preview. It Converts String to a corresponding trait class holding a json and vice versa.

public class SugarCrmSocialSitesParameterConverter implements PreviewParameterConverter<Object> {
    @Override
    public SugarCrmAccount fromString(String string) {
        ObjectNode node = JsonNodeFactory.instance.objectNode();
        if (string.contains(SugarCrmAccount.FIELD_FACEBOOK)) {
            node.put(SugarCrmAccount.FIELD_FACEBOOK, SugarCrmAccount.FIELD_FACEBOOK);
        }
        ... other social sites ...
        return new SugarCrmAccount(node);
    }
    @Override
    public String toString(Object object) {
        if (object instanceof LinkedHashSet) {
            LinkedHashSet set = (LinkedHashSet) object;
            if (set != null &amp;&amp; !set.isEmpty()) {
                String[] parameters = (String[]) set.toArray(new String[set.size()]);
                return StringUtils.join(parameters, "-");
            }
        }
        return null;
    }
}

Page tree