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.

(warning) 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:

  1. Stop the application server.
  2. 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
  3. Restart the server.
  4. Go to the AdminCentral URL.
  5. Start the Web update process.
  6. Click Start up Magnolia.

Repeat the steps for each author and public instance.

Uninstalling

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

(warning) 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

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

 

SugarCrmCommand parameters
DescriptionConstant in info.magnolia.sugarcrm.command.SugarCrmCommandDefault valueAvailable values
PathPARAMETER_PATH = "sugarCrmPath"Empty stringA string representing path after module name
MethodPARAMETER_METHOD = "sugarCrmMethod"Not defined

info.magnolia.sugarcrm.command.SugarCrmCommand#

METHOD_GET / METHOD_PUT / METHOD_POST

Request bodyPARAMETER_BODY = "sugarCrmBody"Empty bodyan 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;
    }
}

Sample traits example

Read more

#trackbackRdf ($trackbackUtils.getContentIdentifier($page) $page.title $trackbackUtils.getPingUrl($page))